Run dxb checks and pushes in CI

Set up a continuous integration (CI) pipeline that validates your docs on every pull request and publishes them to Doxbrix when changes merge. At the end, a failing lint or documentation check blocks the merge, and a merge to your main branch updates the live site without anyone running dxb by hand.

Use this guide when your docs live as local files in a repository and you push them with dxb. If you want Doxbrix to sync with the repository directly instead, see Sync a project with a Git repository.

Before you begin

• A local docs project that is already linked to a Doxbrix project, with .doxbrix/config.json committed to the repository. See Tutorial: author docs locally with dxb.
• A CI system that runs Node.js 22 or later, such as GitHub Actions or GitLab CI.
• Permission to add secret variables to the CI project.

How dxb behaves in CI

Four behaviors matter in a pipeline:

• Authentication comes from the environment. dxb reads a token from --token, then DOXBRIX_TOKEN, then a saved profile. In CI, set DOXBRIX_TOKEN and don't run dxb login.
• Prompts don't wait. When stdin or stderr is not a terminal, every yes/no confirmation takes its default answer, which is no. The command prints Aborted. and exits with code 0, so the job looks successful even though nothing was published. Pass --yes (-y) to confirm prompts up front.
• Machine-readable output goes to stdout. With --json, a command writes one JSON document to stdout and human messages to stderr. On failure it writes { "error": …, "code": …, "hint": … } to stdout unless the command already wrote its own report.
• Exit codes are stable. Branch on them in scripts. See Exit codes.

Set up the pipeline

dxb auth token create "ci docs publish" \
  --scopes docs:read --scopes docs:write --scopes project:read \
  --expires-in-days 365

npx --yes @doxbrix/cli@latest lint --strict

npx --yes @doxbrix/cli@latest push --publish --yes --strict

name: Docs
on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install --global @doxbrix/cli
      - run: dxb lint --strict

  publish:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: check
    runs-on: ubuntu-latest
    env:
      DOXBRIX_TOKEN: ${{ secrets.DOXBRIX_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install --global @doxbrix/cli
      - run: dxb whoami
      - run: dxb push --publish --yes --strict

Verify

After the publish job finishes, its log ends with lines such as:

✓ Pushed 12 page(s): 0 created, 2 updated, 1 space(s).
→ Published pages, search, and AI are updated.

Open the reader site and confirm your change is live. If the log shows Aborted. instead, the job ran without --yes and nothing was published.

Add the documentation check gate

dxb docs check is a stricter gate for teams that maintain a documentation brief. It combines lint, the brief and reader-coverage plan, page contracts, links, evidence receipts, source freshness and example verification. It needs no login or network access.

dxb docs check --source product=../product --base origin/main --strict

The check fails with exit code 2 and Documentation check failed with N error(s). if .doxbrix/documentation.json is missing, the brief is incomplete, or no reader-coverage row exists. Set these up once with dxb docs setup. With --json, the command writes a report whose ok, errors and warnings fields you can read in later steps:

dxb docs check --strict --json > docs-check.json

Exit codes

Every dxb command exits with one of these codes.

Retry only codes 5 and 6; the others need a change to the token, plan or files.

Troubleshooting

For more CLI problems, see Troubleshoot the CLI, Git sync and MCP.

Next steps