Docs Sync Quick Reference

Cheat sheet for the automated documentation sync from the Nexus code repository. Full details: Docs Sync Automation.

How It Works (30 seconds)

1. Developer merges docs to Nexus main
2. Nexus pipeline triggers this repo’s sync job
3. Sync job: clone fixed internal Nexus → verify the commit is on main → diff from tracked state → open a review MR
4. The Nexus author and a docs maintainer both approve, adjust, or reject
5. Merging the MR publishes via the normal build/deploy pipeline

Nothing lands on main without approval. The sidebar order never reshuffles.

Key Files

.gitlab-ci.yml              ← sync job definitions
scripts/docs-sync/
  ├── 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

Ownership Rules

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.

What Happens in a Sync MR

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

Placement Suggestions for New Files

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

Reviewing a Sync MR

• 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

CI/CD Variables (all set in THIS project)

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

Go-Live Checklist

• Merge the sync implementation branch to main here
• Create DOCS_SYNC_BOT_TOKEN (Settings → Access tokens, api scope) and add as CI/CD variable
• Create NEXUS_REPO_READ_TOKEN (any account with Nexus read access → personal access token, read_repository) and add as CI/CD variable
• Set DOCS_MAINTAINER to the docs maintainer’s username
• Confirm every Nexus main merger has Developer+ membership in this project
• Protect nexus-docs main, disallow direct bot pushes, and require sign-off from both the Nexus author and a docs maintainer, plus a successful pipeline
• Merge the Nexus-side dispatch MR
• Merge any doc change in Nexus → verify the sync job log and the opened review MR

Troubleshooting

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