Skip to content

CI recipes

The first-class CI surface is the docsxai GitHub App (webhook on the backend; install-and-go, zero YAML in your repo; see packages/backend/README.md). The recipes below are the documented examples for teams that prefer to drive docsxai run from their own pipelines. They are reference material, not a surface docsxai maintains in your repo.

  • Node 26+ and a Chromium binary (npx playwright-core install chromium).
  • The doc-pack workspace checked out (flows/, docs/, auth/strategy.yaml, .docsxai.json), typically its own repo or a docs/ subdirectory.
  • Target-site credentials as CI secrets, exposed under the env-var names your auth/strategy.yaml declares (creds_env). The descriptor never contains values. Scripted strategies (api-login, jwt-injection, ui-form, totp, test-backdoor, …) regenerate the session per run; manual-capture workspaces are not CI-runnable by design.
  • Zero LLM calls, zero agent context: docsxai run is deterministic: same flows + same target state → byte-identical screenshots (the engine's keystone guarantee).
name: refresh-docs
on:
workflow_dispatch:
schedule: [{ cron: "17 5 * * 1" }] # weekly; or trigger on your app's deploys
permissions:
contents: write
pull-requests: write
jobs:
refresh:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 26 }
- run: npm install --global docsxai@next
- run: npx playwright-core install --with-deps chromium
- name: replay the doc pack
env:
APP_URL: ${{ vars.APP_URL }}
APP_EDITOR_USER: ${{ secrets.APP_EDITOR_USER }}
APP_EDITOR_PASS: ${{ secrets.APP_EDITOR_PASS }}
run: docsxai run ./docs-workspace --base-url "$APP_URL"
- name: render + package
run: |
docsxai render ./docs-workspace
docsxai export adf ./docs-workspace
docsxai zip ./docs-workspace --out doc-pack.zip
- name: open a PR when screenshots changed
uses: peter-evans/create-pull-request@v6
with:
title: "docs: refreshed screenshots"
commit-message: "docs: refresh doc pack"
branch: docs/refresh

The repository root holds a composite action that does the install, the replay, the baseline diff and the pull request comment in one step:

name: docs-drift
on: pull_request
permissions:
contents: read
pull-requests: write
jobs:
drift:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: kalebteccom/docsxai@main
with:
workspace: ./docs-workspace
version: 0.3.0-rc.5
base-url: ${{ vars.APP_URL }}

Pin version to an exact release. Screenshots are byte-identical per docsxai and Chromium build, so a floating tag shows a build change as drift. Inputs: baseline (default .baseline), fail-on (warn or fail, default fail) and comment ("false" skips the pull request comment). The report also lands in the job summary.

A halt (non-zero exit) means drift, not flake: a locator or success criterion no longer holds. The failing step id + halt-cause prefix are in the log and docs/<flow>/halts/<step>.png is the moment of failure. Hand both to your calibration agent (docsxai diagnose). Don't retry.

Keep a committed baseline and fail the pipeline only on meaningful change:

Terminal window
docsxai diff ./docs-workspace --against ./docs-workspace/.baseline --format md --fail-on fail
# exit 0 = no drift (or warnings only), exit 1 = drift at/above the fail threshold
docsxai baseline ./docs-workspace # refresh the baseline after an accepted change

For an unattended nightly version of the same gate, see Nightly drift jobs.

The markdown report is built for PR comments; the GitHub App's pr-comment strategy posts it automatically.

docsxai render writes a static viewer to <workspace>/.viewer/. Deploy that folder under a per-pull-request name and put the link in a comment, so a reviewer opens the screenshots without checking out the branch. The deploy tokens are yours: add them as repository secrets.

name: docs-preview
on: pull_request
permissions:
contents: read
pull-requests: write
jobs:
preview:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 26 }
- run: npm install --global docsxai@next
- run: docsxai render ./docs-workspace
- name: deploy the viewer
id: deploy
env:
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
NETLIFY_SITE_ID: ${{ vars.NETLIFY_SITE_ID }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
npx netlify-cli deploy --dir ./docs-workspace/.viewer --alias "pr-$PR_NUMBER" --json > deploy.json
echo "url=$(node -p 'require("./deploy.json").deploy_url')" >> "$GITHUB_OUTPUT"
- name: link it on the pull request
env:
GH_TOKEN: ${{ github.token }}
PR_NUMBER: ${{ github.event.pull_request.number }}
URL: ${{ steps.deploy.outputs.url }}
run: |
gh pr comment "$PR_NUMBER" --body "Docs preview: $URL" --edit-last --create-if-none

The workspace needs committed output (docs/) for render to have something to show, so run it after a replay or against a committed pack. For Cloudflare Pages, swap the deploy step for npx wrangler pages deploy ./docs-workspace/.viewer --project-name <project> --branch "pr-$PR_NUMBER".

refresh-docs:
image: node:26
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"
script:
- npm install --global docsxai@next
- npx playwright-core install chromium --with-deps
- docsxai run ./docs-workspace --base-url "$APP_URL"
- docsxai render ./docs-workspace
- docsxai zip ./docs-workspace --out doc-pack.zip
artifacts:
paths: [doc-pack.zip, docs-workspace/.viewer]

A nightly job answers two questions: does docsxai run still produce the same bytes twice in a row, and has the app drifted from the committed baseline? Each recipe below does the same four things: install, docsxai run --verify-determinism, docsxai diff --against <baseline> --fail-on fail, and upload the markdown reports as an artifact.

Terminal window
docsxai run ./docs-workspace --base-url "$APP_URL" --verify-determinism --format md > determinism-report.md
docsxai diff ./docs-workspace --against ./docs-workspace/.baseline --format md --fail-on fail > drift-report.md

--verify-determinism runs the selected flows 2 times (--runs <2-5> for more), each into its own root under <workspace>/.docsxai-verify/run-<k>/, then compares every file byte by byte: annotations.json, the screenshots, the step markdown, the locators and the halt context. The workspace is only written when all runs agree: run 1's files are copied in, the same bytes a plain run writes. If the runs differ, or a flow halts, the workspace stays as it was, the report names the first differing artefact with a cause (the JSON key path, the changed-pixel region of a PNG, the first differing line of a text file, or the sizes), and the exit code is 1. The run roots are removed when the command ends. The report goes to stdout (--format text|md|json), progress to stderr.

A determinism failure means the page, not the engine, changes between two runs of the same flow: a clock, an animation, a lazy image, a rotating banner. Pin it with the flow's environment block (clock, reduced_motion), wait_for: settled, a hide step or a redaction, then run the check again. Diff only means something once the check passes, which is why the recipes stop at the first failing step.

diff reads only docs/<flow>/screenshots/ and docs/<flow>/annotations.json. A flow with a matrix: writes docs/<flow>/<variant>/..., so diff reports no screenshot drift for it and exits 0. In a workspace that uses matrix flows, replace the diff line with docsxai pack --check --against <pack-dir> (it needs a pack.json in the workspace but no oxipng), and keep the --verify-determinism line as it is.

Do not run browser capture in per-PR pipelines on shared runners. A capture launches Chromium, walks the whole app and takes screenshots, so it competes with every other job on the runner for CPU and memory, and it needs target credentials that a pull request from a fork must never see. Schedule it (nightly, or on a deploy of the target app) on a runner you control, and keep per-PR pipelines to the checks that need no browser, such as docsxai lint and docsxai flow-tree.

docsxai lint exits 1 on any warning or error, so a per-PR job fails on R017 (a flow whose name: differs from its file name) as it does on any other warning. A misspelt or repeated flag in a recipe exits 2 before the command does any work. It used to run with the flag ignored, so a recipe copied from an older docsxai can start failing after an upgrade.

The recipes install with npm install --global docsxai@next because a plain Node image has npm and nothing else to set up; pnpm add -g docsxai@next works the same where pnpm is already on the runner. The pin is next because pack, --verify-determinism and matrix flows are in 0.3.x, which is on the next dist-tag while latest stays 0.2.0; when 0.3.x ships stable, latest moves to it and the pin should move to the stable version. The weekly refresh and GitLab recipes above install docsxai@next too, for the same reason: a bare docsxai resolves to 0.2.0 while latest is there. The docsxai package carries the viewer, so render works from that one install. Pin the actions by commit SHA in your own repository.

The three files below also live under examples/ci/ in the docsxai repository, and a test keeps the copies in this page identical to them.

GitHub Actions nightly drift (schedule and workflow_dispatch)

Section titled “GitHub Actions nightly drift (schedule and workflow_dispatch)”
# Nightly drift check for a docsxai doc pack. Copy this file to
# .github/workflows/docsxai-nightly-drift.yml in the repository that holds the workspace.
#
# Schedule and manual runs only. Do not add pull_request or push triggers: browser capture is
# slow and heavy, and per-PR pipelines on shared runners compete for the same CPU and memory.
# The job replays the flows twice into isolated roots (--verify-determinism), then compares the
# result with the committed baseline. Both reports are uploaded as one artifact, also on failure.
# Pinned to docsxai@next, the 0.3.x line; when it ships stable, latest moves and the pin should too.
name: docsxai-nightly-drift
on:
schedule:
- cron: "17 3 * * *"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: docsxai-nightly-drift
cancel-in-progress: false
jobs:
drift:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: actions/setup-node@v4
with:
node-version: 26
- name: install docsxai and Chromium
run: |
npm install --global docsxai@next
npx playwright-core install --with-deps chromium
- name: verify determinism
shell: bash # adds pipefail, so a failing docsxai fails the step despite the tee
env:
APP_URL: ${{ vars.APP_URL }}
APP_EDITOR_USER: ${{ secrets.APP_EDITOR_USER }}
APP_EDITOR_PASS: ${{ secrets.APP_EDITOR_PASS }}
run: docsxai run ./docs-workspace --base-url "$APP_URL" --verify-determinism --format md | tee determinism-report.md
- name: diff against the baseline
shell: bash
run: docsxai diff ./docs-workspace --against ./docs-workspace/.baseline --format md --fail-on fail | tee drift-report.md
- name: upload the reports
if: always()
uses: actions/upload-artifact@v4
with:
name: docsxai-nightly-reports
path: |
determinism-report.md
drift-report.md
if-no-files-found: ignore
retention-days: 30

GitLab CI nightly drift (pipeline schedule)

Section titled “GitLab CI nightly drift (pipeline schedule)”
# Nightly drift check for a docsxai doc pack. Merge this job into the .gitlab-ci.yml of the
# repository that holds the workspace, then create a pipeline schedule (CI/CD, Schedules) that
# runs it every night. Set APP_URL, APP_EDITOR_USER and APP_EDITOR_PASS as masked CI/CD variables.
#
# The rule below runs the job for scheduled pipelines only. Do not widen it to merge request or
# push pipelines: browser capture is slow and heavy, and per-PR pipelines on shared runners
# compete for the same CPU and memory.
# Pinned to docsxai@next, the 0.3.x line; when it ships stable, latest moves and the pin should too.
docsxai-nightly-drift:
image: node:26
timeout: 1h
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"
script:
- npm install --global docsxai@next
- npx playwright-core install --with-deps chromium
- docsxai run ./docs-workspace --base-url "$APP_URL" --verify-determinism --format md > determinism-report.md
- docsxai diff ./docs-workspace --against ./docs-workspace/.baseline --format md --fail-on fail > drift-report.md
after_script:
- cat determinism-report.md drift-report.md || true
artifacts:
when: always
expire_in: 30 days
paths:
- determinism-report.md
- drift-report.md
# Nightly drift check for a docsxai doc pack. Copy this file to .woodpecker/docsxai-nightly-drift.yml
# in the repository that holds the workspace, then add a cron named docsxai-nightly-drift under the
# repository's Settings, Crons (for example "0 3 * * *"). Needs Woodpecker 3 for from_secret.
# Add the secrets app_url, app_editor_user, app_editor_pass and, for the upload step, s3_access_key
# and s3_secret_key.
#
# The workflow runs for that cron only. Do not add push or pull_request events: browser capture is
# slow and heavy, and per-PR pipelines on shared runners compete for the same CPU and memory.
# Pinned to docsxai@next, the 0.3.x line; when it ships stable, latest moves and the pin should too.
when:
- event: cron
cron: docsxai-nightly-drift
steps:
- name: drift-check
image: node:26
environment:
APP_URL:
from_secret: app_url
APP_EDITOR_USER:
from_secret: app_editor_user
APP_EDITOR_PASS:
from_secret: app_editor_pass
commands:
- npm install --global docsxai@next
- npx playwright-core install --with-deps chromium
- docsxai run ./docs-workspace --base-url "$APP_URL" --verify-determinism --format md > determinism-report.md
- docsxai diff ./docs-workspace --against ./docs-workspace/.baseline --format md --fail-on fail > drift-report.md
- name: show-reports
image: alpine:3
when:
- status: [success, failure]
commands:
- cat determinism-report.md drift-report.md || true
# Woodpecker has no artifact store of its own; this pushes the reports to an S3-compatible bucket.
- name: upload-reports
image: woodpeckerci/plugin-s3
when:
- status: [success, failure]
settings:
bucket: docsxai-reports
endpoint: https://s3.example.com
path_style: true
source: "*-report.md"
target: nightly/${CI_PIPELINE_NUMBER}/
access_key:
from_secret: s3_access_key
secret_key:
from_secret: s3_secret_key
  • Wiki push: configure the workspace's publisher plugin (.docsxai.json → plugins + plugin_capabilities) and run the publisher after run, e.g. @docsxai/plugin-confluence (repo-only, not on npm: wire it by path from a checkout; confluence:push) is idempotent by content-sha, so a no-change run mutates nothing. Credentials via env (CONFLUENCE_TOKEN, CONFLUENCE_EMAIL).
  • Backend persistence: DOCSX_TOKEN=… docsxai push ./docs-workspace --kind run records the refreshed pack as a finalized revision; run history is appended automatically when the workspace is backend-bound.
Made by KalebtecGitHubApache-2.0 licensed