GitHub App: PR check and repo mirror

Plans

Install the app

Organization admins, in Settings → Integrations:

1. Install GitHub App, pick the GitHub account or organization and the repositories it may access.
2. Authorize when GitHub asks: VersoDocs checks that you can see the installation before linking it to your organization.
3. Back in Settings, choose the check mode and whether to post a PR comment (below).

The app asks for: Checks (read & write) to report the check, Pull requests (read & write) to read the PR and post the optional comment, Contents (read & write) for the mirror, and Metadata (read). One GitHub installation per VersoDocs organization.

PR check: VersoDocs references

Cite the spec a PR implements, in the PR description or in any changed file. Copy it with Copy reference for PRs on the document page: Team+

versodocs:acme/0b6c2d8e-1f2a-4b3c-9d4e-5f6a7b8c9d0e@v12

The form is versodocs:<orgSlug>/<documentId>@v<N>; a document link with ?v=<N> works too. Same syntax as the CLI pr-check and the MCP check_reference tool. On every push and PR edit, the check resolves each reference:

Conclusion: success when every reference is Current (or none is cited). Otherwise, in warn mode (default) the check is neutral: visible, never blocking. In fail mode it fails, so branch protection can require it. Set the mode in Settings → Integrations.

| Document     | Reference                    | Status                       | Found in       |
| ------------ | ---------------------------- | ---------------------------- | -------------- |
| Payments API | versodocs:acme/0b6c…@v12     | Outdated: Current is v13     | PR description |
| Auth flows   | versodocs:acme/7f21…@v4      | Current                      | src/auth.ts    |

• PR comment (optional): one summary comment per PR, updated in place on each run instead of piling up.
• Only references to non-private workspaces of the linked organization are resolved.
• Per run, up to 25 references and the first 100 changed files are read; the summary says when a large PR was only partly scanned.

Repo mirror (Pro)

Keep a folder of a repository equal to the approved Current documents of a VersoDocs workspace. Each time a document is published, the mirror writes it as Markdown, in one commit per sync. Pro

1. In Settings → Integrations, under a workspace, set the repository, branch and base path (e.g. docs/specs). The app must have access to that repository.
2. Optionally turn on AGENTS.md.
3. Sync now writes everything once; later publishes sync automatically. Full resync rewrites every file, e.g. after edits were made in the repo.

Files follow the workspace's folder structure, one .md per document, with front matter: title, versodocs_reference (the reference to cite in PRs), version, url and status: approved. A header comment says the file is managed by VersoDocs: edits made in the repo are overwritten on the next publish, so propose changes in VersoDocs. Deleted or unpublished documents are removed.

AGENTS.md is an index for AI coding agents (Claude Code, Codex, Cursor, Copilot): it lists each mirrored document with its version, says these are the approved specs to implement against, asks agents to cite versodocs_reference in their PRs (so the check above can follow them) and to propose changes in VersoDocs instead of editing the files.

Sync status and the last error show in Settings. Failed syncs are retried hourly.

App or CLI?