Git sync

With Git sync the platform builds the docs itself. A push to the production branch publishes the site. Every pull request (GitHub) or merge request (GitLab) gets a preview site, a commit status and a comment with its link. Self-managed GitLab and GitHub Enterprise work too.

Connect a repositoryCopy Anchor Link

Automatic installCopy Anchor Link

orbitdocs build compiles your Nest app, one folder above the docs app, to extract the spec, so both apps need their dependencies. With an empty Install Command, the platform installs every folder from the repository root down to the root directory that has a lockfile, top-down:

• A workspace (pnpm-workspace.yaml, or workspaces in package.json) is installed once, at its root, which covers the apps inside it.
• Separate apps, such as package-lock.json in the repository root and another in docs/, are each installed: the Nest app first, then the docs app.
• No lockfile above the docs app: the docs app and its parent folder get npm install when they have a package.json.

The build log starts with the folders it installs, such as Install: automatic, from ., docs. The platform image has npm, pnpm and Yarn (through Corepack); Bun is not included, so set your own install command for Bun or add it to the image.

Your Nest app is then compiled by orbitdocs build through build in your docs config (nest build, set by orbitdocs init). To do something else, enter your own install command; it replaces the automatic install and runs in the root directory.

What each event doesCopy Anchor Link

Commit statuses and commentsCopy Anchor Link

The platform reports on each commit as OrbitDocs:

When a preview is ready, the request gets a comment: Docs preview for the short commit hash, with the URL, and a table with every spec's Spectral errors and warnings. Each row says whether the spec matches a registry revision (r4 (unchanged)) or is changed. When the lint gate is on and a spec has errors, the comment says production will refuse it. The success status adds the error count, such as Preview ready · 2 lint errors.

📘 **Docs preview** for 5e50d3c8: https://payments--mr-7.docs.acme.com/

| API | Spectral lint | Registry |
| --- | --- | --- |
| `payments` v2.4.0 | ✗ 1 error, 5 warnings | changed |
| `users` v1.0.0 | ✓ No problems | r4 (unchanged) |

Previews never add registry revisions; their lint counts are also shown on the deployment and the build in the dashboard. Without a token, nothing is reported back, and only public repositories can be cloned.

How a build runsCopy Anchor Link

1. Clone the repository into DATA_DIR/builds/<build id> and check out the exact commit. The token is given to Git for the clone and fetch only, as an HTTP header in Git's environment. It is never in the clone URL, the log or .git/config, so install and build commands can't read it.
2. Install (automatically, or with your install command), then run the build command in the root directory, with the build environment.
3. Publish the output directory and the specs in <root directory>/openapi/, exactly like orbitdocs publish. The base path comes from the build's .orbitdocs/build.json. The log ends with each spec's lint counts.
4. Delete the build folder.

Each step is killed after BUILD_TIMEOUT_MS (default 15 minutes). The log streams into Builds; select a build to read it, with each spec's lint counts above the log. The token and the values of build environment variables (6 characters or longer) are masked as *** in the log.

The platform image includes Node 22, git, npm, pnpm and Yarn (through Corepack). Builds run inside the platform container.

Build environmentCopy Anchor Link

Install and build commands don't get the platform's environment, so PLATFORM_SECRET, DATABASE_URL, ADMIN_PASSWORD, SSO client secrets and the secrets of hosted sites never reach them. They get only:

NODE_ENV is not passed from the platform: its production would make npm ci skip the devDependencies the build needs. Set it as a build variable if your build wants it.

Build environment variables are for values your build needs, such as an API base URL or a private registry token:

• Add a name and a value, then Add. Adding an existing name replaces its value, after a confirmation: the old value can't be shown or restored.
• Removing a variable (the trash icon) also asks first.
• Values are encrypted with PLATFORM_SECRET (AES-256-GCM). The dashboard and the API list names only; a value is never shown again.
• Names use letters, digits and _, and don't start with a digit. CI, ORBITDOCS_PLATFORM_BUILD, GIT_TERMINAL_PROMPT, PATH and HOME are reserved. Up to 100 variables of 16 KB each.
• Changes are written to the audit log as git.configured, with the names added (+NAME) or removed (-NAME), never the values.

Through the API, PATCH /api/projects/<slug>/git takes env: a string sets a variable, null removes it, and variables left out stay as they are.

{ "env": { "API_BASE_URL": "https://api.acme.com", "OLD_FLAG": null } }

The build queueCopy Anchor Link

Builds wait in a queue kept in the platform's own Postgres (pg-boss, in its own pgboss schema). Nothing is lost on a restart, and several platform instances can share the work.

Build statuses: queued, running, succeeded, failed, cancelled. The Builds tab shows the 50 newest.

Self-managed GitLab and GitHub EnterpriseCopy Anchor Link

Set the API URL to your instance's API. The clone URL and the dashboard's Repository link are derived from it:

A Clone URL you set wins over the derived one, and the Repository link follows it. A local path (for testing) has no Repository link.

The token is sent to HTTPS clone URLs as HTTP Basic authentication (x-access-token on GitHub, oauth2 on GitLab).

DisconnectCopy Anchor Link

Disconnect in Settings → Git, after a confirmation, removes the settings, the stored token, the webhook secret and the build environment variables. Existing deployments stay. Remove the webhook in your provider too.

Test webhooks locallyCopy Anchor Link

The repository has two scripts for trying Git sync without a real provider:

node scripts/mock-gitlab.mjs   # a stand-in GitLab API on http://localhost:8092/api/v4
node scripts/webhook.mjs <webhook url> <secret> gitlab push main <sha> "Update docs"
node scripts/webhook.mjs <webhook url> <secret> gitlab mr open 42 feature <sha> "Add guide"
node scripts/webhook.mjs <webhook url> <secret> github pr opened 7 feature <sha>

The mock records the statuses and comments it receives at GET http://localhost:8092/calls.

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link