Cheat sheet for the automated documentation sync from the Nexus code repository. Full details: Docs Sync Automation.
- Developer merges docs to Nexus
main
- Nexus pipeline triggers this repo’s sync job
- Sync job: clone fixed internal Nexus → verify the commit is on
main → diff from tracked state → open a review MR
- The Nexus author and a docs maintainer both approve, adjust, or reject
- Merging the MR publishes via the normal build/deploy pipeline
Nothing lands on main without approval. The sidebar order never reshuffles.
.gitlab-ci.yml ← sync job definitions
├── lib.sh ← doc patterns + placement rules (edit here!)
├── merge.sh ← incremental sync → review MR
├── release.sh ← versioned snapshots → review MR
├── state.json ← last reviewed Nexus main commit
├── test.sh ← source and input security checks
└── path-map.tsv ← nexus path → site page ownership map
src/content/docs/nexus/ ← holding area for unplaced new files
| File |
Owner |
Sync effect |
Listed in path-map.tsv |
Nexus |
Body replaced on Nexus edits (frontmatter kept); no sidebar change |
| Docs-side pages (like this one) |
This repo |
Never touched by the sync |
Under src/content/docs/nexus/ |
Nexus |
Parked awaiting placement; no sidebar entry |
Hand-editing a mapped page? Your body edits will be overwritten by the next sync MR for that file. Remove its path-map.tsv line to reclaim ownership.
| Change in Nexus |
Result in the MR diff |
| Edit to a mapped file |
Site page body updated in place |
| Brand-new file |
Page created in a suggested section + sidebar entry appended + mapping recorded — approve or move it |
| New file, no good suggestion |
Parked in src/content/docs/nexus/, flagged for your decision |
| Deleted mapped file |
Site page + its sidebar entry removed |
| Rename |
Old page removed, new path placed as a new file (no redirect) |
| Code-only merge |
No MR — job exits in seconds |
| Nexus path |
Goes to |
Sidebar group |
docs/decisions/* |
concepts/ |
Architecture Decisions (ADRs) |
docs/architecture/* |
concepts/ |
Key Concepts |
docs/reference/* |
reference/ |
Reference |
docs/security/* |
security/ |
Security |
docs/runbooks/*, docs/ops/* |
operations/ |
Operations |
docs/dev/* |
contributing/ |
Contributing |
docs/perf/* |
contributing/ |
Testing & Performance Baselines |
docs/process/*, docs/community/*, docs/legal/* |
contributing/ |
Governance & Process |
docs/guides/* |
getting-started/ |
Getting Started |
Anything else (services/*/README.md, …) |
holding area |
none |
- Approve: merge — done
- Move a new page: relocate the file, adjust the sidebar entry in
astro.config.mjs, and update its path-map.tsv line; future syncs follow your decision
- Reject a new page: delete the file, its sidebar entry, and its
path-map.tsv line
- Retried triggers force-push the same
sync/nexus-main branch — the existing MR updates, no duplicates
| Variable |
Required |
Value |
DOCS_SYNC_BOT_TOKEN |
✅ |
Project access token, api scope (pushes branches, opens MRs) |
NEXUS_REPO_READ_TOKEN |
✅ |
Token with read_repository on the internal Nexus repo (a personal access token works; no Nexus project settings required) |
DOCS_MAINTAINER |
✅ (required for two-person sign-off) |
Your GitLab username — auto-requested as reviewer on every sync MR, alongside the Nexus author |
| Symptom |
Check |
| No triggered pipeline appears |
Nexus merger lacks Developer+ here, or the hardened Nexus dispatch job is not merged and green |
| Clone fails |
NEXUS_REPO_READ_TOKEN missing/expired |
| Commit is rejected |
The SHA is malformed, absent from internal Nexus, or not on canonical main |
| State ancestry fails |
Internal main was rewritten or state.json is invalid; reconcile manually |
| MR creation fails |
DOCS_SYNC_BOT_TOKEN missing api scope or expired |
| Wrong placement suggested |
Fix it in the MR; tune suggest_section() in scripts/docs-sync/lib.sh for next time |
| Docs-side page changed unexpectedly |
It’s listed in path-map.tsv — remove the line to reclaim ownership |
