Docs sync quick reference

Use this page when reviewing a sync or recovering from a failed run. See Documentation sync automation for the full configuration and ownership model.

Sync and publication

1. The Nexus pipeline dispatches a downstream pipeline to this docs repository.
2. The receiver verifies the source commit and compares it with the last reviewed sync state.
3. Documentation changes create or update the sync/nexus-main review branch.
4. Reviewers approve or adjust the changes. GitLab project settings enforce required approvals.
5. Merging the docs merge request into main runs validation, build, and deployment.

Release triggers instead create a snapshot review branch named release/docs-<tag>.

Rerun after a fix

After the fix is merged into docs main, open the Nexus pipeline and retry docs-sync-dispatch in the sync stage. Open the newly created downstream docs pipeline and verify its commit includes the fix.

• Retrying the existing downstream docs pipeline uses its original docs commit.
• Run pipeline in the docs project does not select the receiver jobs; they require a cross-project trigger.
• An existing pending branch for the same Nexus commit is left unchanged. A newer source commit can force-push a refreshed branch, so merge manual placement edits before dispatching another sync.

Review the incoming changes

Incoming change	Review action
Updated mapped page	Check the body changes, links, and technical accuracy. Its sidebar position stays the same.
New page with a suggested location	Confirm the destination, title, sidebar group, and source mapping.
File under sync-pending/	Decide whether to publish or exclude it. Pending files are outside the live site, search index, and sitemap.
Deleted mapped page	Confirm the source deletion is intended and check references to the removed page.
Renamed source file	Review both the removal and proposed replacement; redirects are not generated automatically.

To move or publish a page: Place it under src/content/docs/, update astro.config.mjs, and record the source-to-site path in scripts/docs-sync/path-map.tsv.

To reject a page: Remove the file, sidebar entry, and mapping, then exclude its source in is_site_docs_path() in lib.sh so later changes do not reimport it.

After editing placements, run:

python3 scripts/docs-sync/finalize.py
sh scripts/validate-llms-txt.sh
npm run build

Content ownership

Page type	Update behavior
Mapped in path-map.tsv	Nexus owns the body. Sync preserves title and description, refreshes lastReviewed, and defaults a missing owner to Engineering.
Curated docs-side page	Maintained here. Source changes require manual review.
Unplaced file in sync-pending/	Stored for review without publication.

Testing, Wire Contracts, and the Claude Code session checklist are curated docs-side pages. Their Nexus source paths are excluded from live imports and retained as link aliases.

To reclaim another mapped page, remove its mapping, exclude its source in is_site_docs_path(), and add a link-map.tsv alias if other pages link to it.

Configuration variables

Configure these in the docs project’s Settings → CI/CD → Variables. Mask credentials and protect them for docs main.

Variable	Required?	Purpose
NEXUS_GIT_HOST	Yes	Canonical Nexus host, owned by the receiver configuration.
DOCS_SYNC_BOT_TOKEN	Yes	Project access token with api scope and permission to push sync branches and open merge requests.
NEXUS_REPO_READ_TOKEN	Unless job-token access is configured	Token with read_repository scope and Nexus read access.
DOCS_MAINTAINER	Optional, recommended	Comma-separated reviewer usernames. Reviewer assignment does not enforce approvals.

When the read token is unset, cloning uses GitLab’s automatic CI_JOB_TOKEN. Nexus must allow inbound job-token access from this project, and the triggering user must have Nexus read access.

Key files

File	Purpose
.gitlab-ci.yml	Receiver job rules and build/deploy jobs
scripts/docs-sync/lib.sh	Authentication, filtering, placement, and merge-request helpers
scripts/docs-sync/merge.sh	Incremental live-page sync
scripts/docs-sync/release.sh	Versioned snapshots
scripts/docs-sync/state.json	Source commit represented by the reviewed sync
scripts/docs-sync/path-map.tsv	Source-to-site body ownership
scripts/docs-sync/link-map.tsv	Link aliases for curated pages
scripts/docs-sync/finalize.py	Link translation, duplicate-route checks, sidebar destinations, and discovery entries

Troubleshooting

Symptom	Check
No downstream pipeline	Triggering user needs Developer access in the docs project; check the Nexus dispatch job.
Clone fails	Check token expiry, scope, and read access, or the job-token allowlist and triggering user’s access.
Retry still runs old code	Retry the upstream dispatch job and open the new downstream pipeline.
Commit rejected	Use a full commit identifier reachable from canonical Nexus main.
State ancestry fails	Reconcile rewritten history or incorrect sync state before retrying.
Merge-request creation fails	Check bot-token permissions, api scope, and expiry.
Wrong placement	Update the page, sidebar, and mapping together; adjust placement rules for future imports.
Local formatting disappears	The page is body-mapped. Make the change in Nexus or explicitly reclaim docs-side ownership.