Onboarding

This page covers the procedure to enroll a new repository in the docs-control governance system and configure documentation pipelines and Antigravity AI automation.

Prerequisites

Org membership in f5-sales-demo
REPO_SETTINGS_TOKEN and REPO_SYNC_TOKEN secrets configured as organization-level secrets (or added to the new repository individually)
ANTIGRAVITY_TOKEN and GCP_PROJECT_ID secrets configured for automated Antigravity AI code review and language translation
Access to the ghcr.io/f5-sales-demo/docs-builder container image

Enrollment steps

1. Add to downstream-repos.json

Add the repository’s bare name — not owner/repo — to .github/config/downstream-repos.json in docs-control. The owner is prepended at dispatch time from GITHUB_REPOSITORY_OWNER. This registers it for dispatch and enforcement.

Then assign it a class in repo_classes.repos in .claude/governance.json. This is required: shell unit tests fail if a repository is registered for dispatch without a class assignment.

2. Optionally add to docs-sites.json

If the repository will publish documentation, add an entry to .github/config/docs-sites.json with:

label — human-readable site name
url — URL to the site’s llms-full.txt endpoint
description — short description used in the generated README

If no entry is added, the README generator falls back to a capitalized repository name and the GitHub API description.

3. Consolidate .gitignore

The enforcement workflow overwrites the downstream .gitignore entirely. Before onboarding, merge any repository-specific entries into the template .gitignore in docs-control so they are not lost.

4. Install caller workflows

Copy the caller workflow templates from workflows/ in docs-control into the new repository’s .github/workflows/ directory:

enforce-repo-settings.yml — triggers enforcement and file sync
github-pages-deploy.yml — triggers docs build and deploy
require-linked-issue.yml — enforces PR-to-issue linking
antigravity-review.yml — triggers Antigravity AI PR code review
antigravity-translate.yml — triggers Antigravity AI language translation
super-linter.yml — runs the super-linter suite on PRs
dependabot-auto-merge.yml — auto-merges green dependabot PRs

These files are also synced automatically by the file sync workflow, but installing them manually bootstraps the process.

5. Trigger enforcement

Run the enforcement workflow manually in the new repository:

source_sha=$(gh api repos/f5-sales-demo/docs-control/commits/main --jq '.sha')
gh workflow run enforce-repo-settings.yml \
  --repo f5-sales-demo/<repo-name> \
  -f source_sha="$source_sha"

This applies all repository settings, creates any missing governance files, and opens a sync PR if needed.

6. Verify settings

Confirm that enforcement succeeded:

gh run list --repo f5-sales-demo/<repo-name> --workflow enforce-repo-settings.yml --limit 1

Check that branch protection, Actions permissions, and Pages are configured correctly:

gh api repos/f5-sales-demo/<repo-name>/branches/main/protection \
  --jq '.required_status_checks.contexts'

7. Verify docs site

If the repository has a docs/ directory, confirm the docs site is accessible after the first successful deploy:

curl -sf "https://f5-sales-demo.github.io/<repo-name>/" \
  && echo "OK" || echo "FAIL"

Fork-fidelity: opting out of managed files

Most governed repositories take every managed file as-is, but active forks can opt out of sync on specific paths using skip_files in repo-settings.json under managed_files and .claude/governance.json.