Adding a Maintainer

Checklist for onboarding a new maintainer to this repository. Most of it is ordinary GitLab membership; the last two sections wire them into the docs-sync automation.

1. Add them as a project member

1. Go to Settings → Members (left sidebar: Manage → Members)

2. Click Invite members

3. Enter their GitLab username or email

4. Choose a role:

   Role	Grants	Use for
   Developer	Push branches, open/review MRs, run pipelines	Contributors, and anyone who merges to Nexus main (their docs-sync trigger runs with their permissions)
   Maintainer	Everything above + merge to protected main, manage CI/CD variables, protected branches, access tokens	Docs maintainers
   Owner	Everything + member management, project deletion	Sparingly

5. Leave Access expiration date empty for permanent maintainers

6. Click Invite

For a docs maintainer, choose Maintainer — they need to merge sync MRs into protected main and manage the CI/CD variables below.

2. Add them as a docs-sync reviewer

The sync automation auto-requests reviewers on every sync MR from the DOCS_MAINTAINER CI/CD variable.

1. Go to Settings → CI/CD → Variables

2. Edit DOCS_MAINTAINER

3. Append the new maintainer’s GitLab username, comma-separated, no spaces:

   aszalea,newmaintainer

4. Save

From the next sync onward, they are requested as a reviewer on every docs-sync MR alongside the Nexus author. Unresolvable usernames are skipped with a log line (the sync never fails over reviewer assignment), so double-check the spelling in the next sync job log.

3. Make sure they can approve sync MRs

If the project uses approval rules (Settings → Merge requests → Merge request approvals), add the new maintainer to the relevant approval rule so their review counts toward the required approvals.

4. Hand over token knowledge (no action usually needed)

Two CI/CD tokens power the sync; a new maintainer should know where they live and when they expire:

Variable	What it is	Rotation
DOCS_SYNC_BOT_TOKEN	Project access token (api scope, Developer role) created in this project’s Settings → Access tokens	Recreate the token, update the variable
NEXUS_REPO_READ_TOKEN	Token with read_repository on the Nexus repo (group access token preferred; a personal access token also works)	Same

Personal-token bus factor

If NEXUS_REPO_READ_TOKEN is a personal access token, it stops working when its owner loses Nexus access or lets it expire. When onboarding a new maintainer is prompted by someone leaving, check whose token this is and re-issue it — ideally as a group access token (read_repository, Reporter role) so it isn’t tied to a person.

5. If they also merge code in Nexus

Anyone who merges to Nexus main needs at least Developer membership in this project, or their docs-sync trigger job fails on the Nexus side (the native trigger: keyword runs with the merger’s permissions). Step 1 already covers this for the new maintainer; keep it in mind for Nexus-only engineers too.

Offboarding (reverse checklist)

1. Remove their username from DOCS_MAINTAINER (Settings → CI/CD → Variables)
2. Remove or downgrade their membership (Settings → Members)
3. If any sync token was their personal token, re-issue it from another account or as a group token and update the CI/CD variable
4. Update approval rules if they were listed

Related Documentation

• Docs Sync Automation — full sync architecture and configuration
• Docs Sync Quick Reference — variables table and go-live checklist