> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devtune.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitBook change requests

> Connect GitBook with a personal access token, map your site to GitBook spaces, and open change requests from action drafts. Merging marks the action live.

> [!NOTE]
>
> GitBook change requests are available on every plan with content drafts.
> Content drafts are covered in [Content
> drafts](https://docs.devtune.ai/insights-actions/content-drafts.md).

If your docs live in GitBook, DevTune can open a change request from an
action's content draft instead of you copying the draft by hand. You review
and merge it in GitBook, under your space's own merge rules. DevTune never
merges.

When the change request is merged, the action is marked live and its
before/after window opens in [Results](https://docs.devtune.ai/insights-actions/outcomes.md).

If your GitBook space syncs with a GitHub repository, you can map the same
pages through [GitHub pull requests](https://docs.devtune.ai/integrations/github-pull-requests.md)
instead. Each site address belongs to one source, so pick one.

## Before you connect

You need:

* project management permission in DevTune;
* a GitBook personal access token. GitBook doesn't offer DevTune an app or
  OAuth sign-in, so DevTune works with a token you create.

A token has every permission of the GitBook member who created it. Create it
as a **dedicated GitBook member**, such as `docs-bot@example.com`, rather than
your own account:

* A personal token stops working when its owner leaves or loses access.
* Change requests opened with a dedicated member's token aren't attributed to
  one person.
* Give that member the **Editor** role, the lowest GitBook role that can
  create change requests. An Editor can't merge them. A **Reviewer** or a
  higher role can, and a space's own permissions can raise a member's role
  there.

GitBook counts every member of an organization toward billing, whatever their
role, so a dedicated member takes a seat. See [GitBook's
roles](https://gitbook.com/docs/collaborate/member-management/roles). A
member's own token also works, and DevTune shows whose token it is.

To create the token, sign in to GitBook as that member and open [Developer
settings](https://app.gitbook.com/account/developer).

## What DevTune can touch

The token can do whatever its GitBook member can. DevTune uses it only to:

* read your organization's sites, spaces and pages;
* create change requests in the spaces you map, write the draft to them, and
  open, update or archive them;
* check whether they were merged.

DevTune never merges a change request, whatever the token allows. It doesn't
edit the main content of a space, reorder navigation or change merge rules. A
new page goes last under its parent page; move it in the change request if it
belongs elsewhere.

This connection is separate from the GitBook connection in AI Traffic. A token
connected there is never used to write. You can paste the same token into
both.

## Connect GitBook

1. Open your project's **Settings** and select the **Integrations** tab.
2. Under **Content repositories**, select **Connect GitBook**.
3. Paste the token into **GitBook personal access token** and select **Connect
   GitBook**.
4. If the token's member belongs to more than one GitBook organization, choose
   the **GitBook organization** and select **Connect GitBook** again.

The organization appears under **Content repositories** as **Connected**, with
**Connected as** and the name and email of the token's GitBook member. Every
project in the DevTune account can use a connected organization. To connect
another organization, select **Connect GitBook** again with a token that
reaches it.

### If connecting fails

| Message | What to do |
| - | - |
| **GitBook rejected this token.** | Check you copied the whole token, or create a new one |
| **This token belongs to no GitBook organization.** | Add the token's member to your GitBook organization, then try again |
| **That GitBook organization is already connected. Replace its token instead.** | Select **Replace token** on the organization's row |
| **This GitBook connection changed. Reload and try again.** | Someone disconnected, reconnected or replaced the token while you did. Reload the page and replace the token again if you still need to |
| **Only account managers can connect GitBook.** | Ask an account manager to connect |
| **GitBook did not answer. Try again.** | Try again in a minute |

## Content sources

A GitBook content source maps a site address onto a space:

| Site address | Space |
| - | - |
| `docs.example.com/` | `Example Docs` |
| `docs.example.com/api/` | `API reference` |

To add a content source:

1. Under **Content repositories**, find **Add a content source**.
2. If you also connected GitHub, set **Hosted on** to **GitBook**.
3. If you connected more than one GitBook organization, choose the **GitBook
   organization**.
4. Select one of the suggested site addresses. DevTune suggests the address
   GitBook publishes each space at, and selects its **Space**. A GitBook
   source's site address must be one GitBook publishes its space at.
5. Select **Add source**.

| Message | What to do |
| - | - |
| **This token can't edit that space.** | Give the token's member edit access to the space in GitBook, then try again |
| **GitBook could not find that space. Pick one from the list.** | Select a space from **Space** |
| **Enter a site address such as docs.example.com or example.com/blog.** | Enter the address without `https://`, as a host and optional path |
| **Another source already covers that site address.** | Remove the other source first |
| **GitBook doesn't publish that space at this site address. Pick one of its suggested addresses.** | Select one of the suggested addresses for the space |
| **This GitBook member can't list your sites.** | Give the token's member access to your GitBook sites, or replace the token with one from a member who has it |
| **GitBook's rate limit for this token is used up. Try again in a minute.** | Wait a minute and try again |
| **Some spaces didn't load. Try again in a minute.** | The list shows the spaces DevTune found. Reload the page in a minute to load the rest |

Each source row can also show:

* **This token can also merge change requests in this space. DevTune never
  merges.** The token's member can merge there. DevTune still won't; to have
  GitBook enforce it too, give that member the Editor role in the space.
* **GitBook syncs this space with** a repository. A merged change request
  reaches that repository through GitBook's Git Sync.

A page belongs to the source with the longest matching site address, across
GitHub and GitBook sources. Each site address can belong to only one source in
a project.

To remove a source, select **Remove** beside it. Pages under that address can
no longer get change requests. Open change requests stay open in GitBook.

## Open a change request from a draft

You need project management permission.

1. Open an action with a content draft.
2. In the **Draft** section, select **Create change request**.

DevTune opens the change request for the latest draft version and links it as
**Change request #** with its number. Each action has one change request at a
time.

**Refresh actions.** The page's path under the source's site address is its
path in the space: `docs.example.com/guides/quickstart` is the page
`guides/quickstart`. DevTune reads the live page and applies every section
edit to it. If any change doesn't match the page, nothing is written. If no
page is found, enter its **Page path** and select **Try again**.

**Create actions.** DevTune adds a new page at the brief's target path, under
the page one level up, which must already exist. The page's title and
description come from the draft.

The change request's subject is the action's title. Its description says
DevTune opened it from a draft approved by the member who created it, links the
action, and lists the brief's acceptance criteria and any facts the fact check
still flags. For a new page, it reminds the reviewer to check where the page
sits in the navigation.

After writing, DevTune reads the page back from the change request. If GitBook
stored it differently from what DevTune wrote, DevTune archives a change
request it just created, so a reviewer never sees an edit nobody meant. On an
update, it leaves the change request open with the reviewer's work in it and
shows the refusal.

DevTune does not open a change request for a [locked
page](https://docs.devtune.ai/insights-actions/actions-hub.md#locked-pages).

### Update a change request

After you select **Generate new draft**, the Draft section shows **The newest
draft is not in this change request yet.** Select **Update change request** to
write the new version to the same change request.

If someone else edited the change request in GitBook, DevTune leaves their
work alone and refuses the update. If the change request is behind the space
and GitBook reports conflicts when DevTune brings it up to date, DevTune writes
nothing. In both cases, make further changes in GitBook, or close the change
request and create a new one.

### Close a change request

Select **Close change request** and confirm. DevTune archives it in GitBook.
The draft stays in DevTune, and you can create a new change request.

## Automatic change requests

Turn on **Open change requests automatically** beside a GitBook content
source. It is off by default.

It works as [automatic pull requests](https://docs.devtune.ai/integrations/github-pull-requests.md#automatic-pull-requests)
do: each new content draft for a page under that source opens the action's
change request, or writes the draft to its open one, as the member who started
the draft run. When GitBook's rate limit is used up, DevTune waits and tries
again later rather than failing.

## Merge in GitBook

GitBook doesn't notify DevTune, so DevTune checks your change requests about
every ten minutes, and when you open the action. The action shows **Checked in
GitBook** with the time of the last check.

* **Merged.** The action is marked live as of the time it merged in GitBook,
  even when DevTune notices later, and its before/after window opens in
  [Results](https://docs.devtune.ai/insights-actions/outcomes.md). A refresh action uses its own page
  URL. A new page uses the source's site address plus the page's path in
  GitBook.
* **Archived.** The change request is recorded as **Closed**. The action is
  unchanged, and you can create a new change request. If someone reopens and
  merges it in GitBook within 90 days of closing, DevTune still marks the
  action live.

### Limits

* DevTune stops checking a closed change request 90 days after it closed.
* When GitBook's rate limit for the token is used up, opening the action shows
  the last recorded state instead of checking. Create, update and close refuse
  until it refills, usually within a minute.
* If an older change request is merged after DevTune stopped checking it,
  select **Mark live** on the action yourself.

## Disconnect and reconnect

DevTune checks the token once a day. A content source shows **Reconnect
needed** when:

* GitBook rejects the token, for example because its member left. The
  organization shows **Reconnect needed** and **GitBook rejected this token.
  Replace it to reconnect.** Account owners get a notice and an email.
* The token's member loses edit access to the source's space. The source says
  **The token can no longer edit this space. Give its GitBook member edit
  access again.** Account owners get a notice and an email. The source
  recovers at the next daily check after you restore access.

To replace the token, select **Replace token** on the organization, paste the
new token and select **Replace token**. The new token can belong to another
GitBook member, such as a dedicated member replacing a personal token, as long
as it reaches the same organization. Sources broken by the old token work
again straight away. DevTune then checks each mapped space with the new token,
and a source whose space the new member can't edit shows **The token can no
longer edit this space.**

To disconnect, select **Disconnect GitBook** and confirm. DevTune deletes the
token and removes every content source on that organization. Change requests
stay open in GitBook, but DevTune stops tracking them, and connecting again
doesn't resume that. After you merge one of them, select **Mark live** on the
action yourself. To remove the token's access entirely, revoke it in GitBook's
[Developer settings](https://app.gitbook.com/account/developer).

## Refusals

When DevTune can't create, update or close a change request, the Draft section
shows why.

| Message | Fix |
| - | - |
| **Content change requests are not available on this account.** | Your plan has no content drafts. Check your plan on **Billing** |
| **This action no longer exists.** | Reload the Actions queue |
| **Generate a draft first.** | Select **Generate draft** in the Draft section |
| **A newer draft replaced this one. Reload the page.** | Reload the page and review the newest draft before creating the change request |
| **Live and archived actions take no change requests.** | Only open actions get change requests |
| **This page is locked, so DevTune does not change it.** | Unlock the page in **Settings › Pages** if you want DevTune to edit it |
| **No content source covers this page. Select one.** | Choose a **Content source** and select **Try again**, or add a source for the page's site address in **Settings** |
| **Reconnect GitBook in project settings, then try again.** | Follow [Disconnect and reconnect](#disconnect-and-reconnect) |
| **Enter a page path inside the GitBook space.** | Enter the **Page path** below the space root, such as `guides/quickstart` |
| **No GitBook page was found for this path. Enter its page path.** | Enter the page's **Page path** and select **Try again**. For a new page, check its parent page exists |
| **A GitBook page already exists at that path. Enter another page path.** | Enter a **Page path** that does not exist yet and select **Try again** |
| **Changes 2, 5 do not match the GitBook page. Generate a new draft, then try again.** | The page changed since the draft was written. Select **Generate new draft**, then try again |
| **The draft does not match the GitBook page. Generate a new draft, then try again.** | The page changed since the draft was written. Select **Generate new draft**, then try again |
| **A change request is already being opened. Try again in a minute.** | Wait a minute and try again |
| **This change request was merged in GitBook, so the action is live and being measured.** | Reload the page |
| **This action has no open change request.** | Reload the page |
| **Someone else edited this change request in GitBook. Update it there, or close it and create a new one.** | Make further changes in GitBook, or close the change request and create a new one |
| **This change request has conflicts in GitBook. Resolve them there, or close it and create a new one.** | Resolve the conflicts in GitBook, or close the change request and create a new one |
| **GitBook stored the page differently from what DevTune wrote. Check the page in GitBook, then try again.** | Check the page in GitBook for content DevTune can't round-trip, then try again |
| **GitBook's rate limit for this connection is used up. Try again in a minute.** | Wait a minute and try again |
| **GitBook refused the request. Try again.** | Try again. If it keeps failing, check the token's member can still edit the space |
| **GitBook was disconnected, so DevTune stopped tracking this change request.** | Connect GitBook again to create a new change request. Mark the action live yourself if you merged the old one |

## API and MCP

Your own agents use the same endpoints and tools as [GitHub pull
requests](https://docs.devtune.ai/integrations/github-pull-requests.md#api-and-mcp). The content source
decides whether DevTune opens a pull request or a change request:

* `GET /api/v2/projects/{projectId}/setup/content-sources` and
  `devtune_get_content_sources` return `provider: "gitbook"` with the `space`
  and the `connection` (organization and GitBook member) for GitBook sources.
* `POST /api/v2/projects/{projectId}/actions/{actionId}/draft/pull-request`
  and `devtune_create_draft_pull_request` accept an optional `pagePath` for a
  GitBook page.

GitBook is connected in the app only; there is no endpoint that takes a token.

## Next steps

* [Generate content drafts](https://docs.devtune.ai/insights-actions/content-drafts.md)
* [Measure shipped actions in Results](https://docs.devtune.ai/insights-actions/outcomes.md)
* [Open pull requests on GitHub](https://docs.devtune.ai/integrations/github-pull-requests.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.