Integrations

GitHub app

The usual way to run Docsmith. Install it on the repositories you want watched — never the whole organisation by default — and it reads pushes and, if you ask it to, opens pull requests.

Permissions, and why

Every permission below is one the app actually uses. If you can think of a way to do the job with fewer, we would like to hear it.

Permission	Level	Why
Contents	Read	Read the diff of a push and the text of documentation pages. Docsmith does not clone the repository to disk.
Contents	Write	Only if you enable pull-request delivery, and only to create the branch that carries a draft.
Pull requests	Write	Open and update the draft PR. The app cannot merge — GitHub enforces that separately, and so do we.
Metadata	Read	Mandatory on every GitHub app. Repository name and topology.
Webhooks: push, pull_request	Subscribe	Know that a change happened, and that a draft PR was closed or merged so the queue stays accurate.

Not requested: Actions, Secrets, Environments, Packages, Deployments, Administration, Members, or write access to Issues. If a future feature needs one, GitHub will ask you to approve the change explicitly.

Path scoping

Two different scopes, and mixing them up is the most common misconfiguration.

Read scope is the whole repository. A change to src/retry.ts has to be readable for Docsmith to know it invalidated a page.
Write scope is only the paths you nominate. A draft can never touch a file outside them, even if the model proposes one.

# .docsmith.yml — committed to the repository root
paths:
  - docs/**/*.md
  - docs/**/*.mdx
  - README.md

ignore:
  - docs/changelog/**
  - docs/v1/**          # archived version
  - "**/generated/**"

delivery: pull_request  # or review_queue (default)
branchPrefix: docsmith/
confidenceFloor: 0.75
quietHours:
  timezone: America/Los_Angeles
  hold: ["Fri 16:00-23:59", "Sat", "Sun"]

Settings in .docsmith.yml override the dashboard, so a repository’s configuration is reviewable in a pull request like anything else. The file is optional.

Monorepos

One repository can hold several documentation sets. Declare them separately and each is scoped, routed and reported on its own.

sets:
  - name: sdk
    paths: ["packages/sdk/docs/**/*.md"]
    watch: ["packages/sdk/src/**"]
    delivery: pull_request

  - name: platform
    paths: ["apps/platform/docs/**/*.mdx"]
    watch: ["apps/platform/src/**", "apps/platform/api/**"]
    delivery: review_queue

watch narrows which source changes can reach that set. On a large monorepo this is worth setting: without it, every change in the repository is a candidate for every set, which is correct but slower and noisier.

What a draft pull request looks like

One branch per draft, named docsmith/<commit>-<page-slug>. The body carries the evidence, not a summary of it:

Docs update for a4f19c2

docs/guides/retries.md — 2 passages affected

## Defaults · breaking · 94%
> By default the client makes up to 5 attempts and waits a fixed
> 200 ms between them.

DEFAULT_ATTEMPTS moved from 5 to 3 and delayMs was replaced by
baseDelayMs, which defaults to 250 with exponential backoff.

---
Caused by a4f19c2 · Model: gpt-4.1 · Sync syn_9f31c0a7b4
Docsmith does not merge. Review the diff before approving.

If a later commit changes the same page again before the PR is merged, Docsmith force-updates the branch rather than opening a second one, and adds a comment saying what changed.

Using it as a status check

Teams that want documentation staleness to be visible during review rather than after can run Docsmith as a check on the pull request itself. It never fails the build by default; it annotates.

# .github/workflows/docsmith.yml
name: docsmith
on: pull_request

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: docsmith/action@v1
        with:
          api-key: ${{ secrets.DOCSMITH_API_KEY }}
          base: ${{ github.event.pull_request.base.sha }}
          fail-on: none   # or: breaking

Setting fail-on: breaking makes the check fail when a finding is severity breaking. Start with none for a fortnight and look at what it would have failed on before you turn it up.

GitLab and Bitbucket

Both are supported with the same model: a project access token with read scope on the repository and write scope on branches and merge requests. Configuration is identical — .docsmith.yml lives in the repository root either way. The setup steps differ slightly and are in Settings → Repositories once you pick the host.

Uninstalling

Remove the app from your GitHub settings, or disconnect from Settings → Repositories. The index is deleted immediately and your sync history is retained for your plan’s window unless you delete the account, in which case everything goes within 30 days. Open draft pull requests are left alone — they are yours, and closing them is your call.

Anything unclear here? Ask us and we will fix the page.