Skip to main content
GitBook change requests are available on every plan with content drafts. Content drafts are covered in Content drafts.
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. If your GitBook space syncs with a GitHub repository, you can map the same pages through GitHub pull requests 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 [email protected], 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. 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.

​
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

​
Content sources

A GitBook content source maps a site address onto a space: 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.
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.

​
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 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. 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.

​
Refusals

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

​
API and MCP

Your own agents use the same endpoints and tools as GitHub pull requests. 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