Configuration Reference

The central configuration file drives all enforcement, sync, and dispatch behavior. It lives at .github/config/repo-settings.json in docs-control and is fetched by downstream repositories at workflow runtime.

{
  "_comment": "Central repo-settings config — enforced by enforce-repo-settings.yml",
  "repository": {
    "private": false,
    "has_issues": true,
    "has_projects": false,
    "has_wiki": false,
    "is_template": false,
    "allow_squash_merge": true,
    "allow_merge_commit": true,
    "allow_rebase_merge": true,
    "allow_auto_merge": false,
    "delete_branch_on_merge": true,
    "web_commit_signoff_required": false,
    "squash_merge_commit_title": "COMMIT_OR_PR_TITLE",
    "squash_merge_commit_message": "COMMIT_MESSAGES",
    "merge_commit_title": "MERGE_MESSAGE",
    "merge_commit_message": "PR_TITLE",
    "allow_update_branch": true,
    "homepage": ""
  },
  "actions_permissions": {
    "default_workflow_permissions": "write",
    "can_approve_pull_request_reviews": true
  },
  "branch_protection": [
    {
      "branch": "main",
      "enforce_admins": true,
      "required_status_checks": {
        "strict": false,
        "contexts": ["check / Check linked issues"],
        "self_contexts": ["Check linked issues"]
      },
      "required_pull_request_reviews": null,
      "restrictions": null,
      "required_linear_history": false,
      "allow_force_pushes": false,
      "allow_deletions": false,
      "block_creations": false,
      "required_conversation_resolution": false,
      "lock_branch": false,
      "allow_fork_syncing": false
    }
  ],
  "topics": [],
  "pages": {
    "enabled": true,
    "build_type": "workflow"
  },
  "managed_files": {
    "source_repo": "f5xc-salesdemos/docs-control",
    "files": [
      {"src": "workflows/github-pages-deploy.yml", "dest": ".github/workflows/github-pages-deploy.yml"},
      {"src": "workflows/enforce-repo-settings.yml", "dest": ".github/workflows/enforce-repo-settings.yml"},
      {"src": "workflows/require-linked-issue.yml", "dest": ".github/workflows/require-linked-issue.yml"},
      {"src": ".github/PULL_REQUEST_TEMPLATE.md", "dest": ".github/PULL_REQUEST_TEMPLATE.md"},
      {"src": ".github/ISSUE_TEMPLATE/bug_report.md", "dest": ".github/ISSUE_TEMPLATE/bug_report.md"},
      {"src": ".github/ISSUE_TEMPLATE/feature_request.md", "dest": ".github/ISSUE_TEMPLATE/feature_request.md"},
      {"src": ".github/ISSUE_TEMPLATE/documentation.md", "dest": ".github/ISSUE_TEMPLATE/documentation.md"},
      {"src": ".github/ISSUE_TEMPLATE/config.yml", "dest": ".github/ISSUE_TEMPLATE/config.yml"},

      {"src": "CONTRIBUTING.md", "dest": "CONTRIBUTING.md"},
      {"src": "CLAUDE.md", "dest": "CLAUDE.md"},
      {"src": ".editorconfig", "dest": ".editorconfig"},
      {"src": ".gitignore", "dest": ".gitignore"},
      {"src": "LICENSE", "dest": "LICENSE"},
      {"src": ".pre-commit-config.yaml", "dest": ".pre-commit-config.yaml"}
    ]
  }
}

Field reference

`repository`

Standard GitHub repository settings applied via PATCH /repos/{owner}/{repo}. Each key maps directly to the GitHub API field. The enforcement workflow compares each key against the repository’s current value and only patches keys that have drifted.

Notable settings:

delete_branch_on_merge: true — automatically cleans up merged PR branches
allow_update_branch: true — enables the “Update branch” button on PRs
homepage: "" — auto-computed at runtime as https://f5xc-salesdemos.github.io/{repo}/

`actions_permissions`

Controls GitHub Actions workflow permissions for the repository:

default_workflow_permissions: "write" — workflows get read/write access to the repository by default
can_approve_pull_request_reviews: true — allows workflows to approve PRs

`branch_protection`

An array of branch protection rules. Each entry specifies a branch name and the desired protection settings. Currently only main is protected.

Key fields:

enforce_admins: true — protection rules apply to repository administrators too
required_status_checks.strict: false — branches don’t need to be up-to-date before merging
required_status_checks.contexts — the check names downstream repositories must pass (e.g., check / Check linked issues)
required_status_checks.self_contexts — the check names docs-control itself must pass (e.g., Check linked issues)
required_pull_request_reviews: null — no PR review approval required
restrictions: null — no push restrictions beyond branch protection

`contexts` vs `self_contexts`

When a downstream repository uses a caller workflow, the status check name becomes <caller_job_key> / <reusable_job_name>. For example, the require-linked-issue.yml caller has job key check, so the check name is check / Check linked issues. But when docs-control runs the same workflow directly (via the pull_request_target trigger), the check name is just Check linked issues.

The self_contexts field stores the check names that apply to docs-control itself. During enforcement, the workflow detects whether it’s running on the source repository and swaps self_contexts into contexts before applying branch protection. The self_contexts field is always stripped before sending the payload to the GitHub API.

`topics`

An array of GitHub topics to apply to the repository. Currently empty — topics are not enforced.

`pages`

GitHub Pages configuration:

enabled: true — ensures Pages is enabled on every enrolled repository
build_type: "workflow" — uses GitHub Actions for the Pages build (not legacy branch-based builds)

`managed_files`

Defines the file synchronization manifest:

source_repo — the repository that holds canonical versions of managed files (f5xc-salesdemos/docs-control)
files — an array of {src, dest} objects mapping source paths in docs-control to destination paths in downstream repositories

The file sync workflow iterates this array to detect and correct drift. Files not listed here (like dependabot.yml and README.md) are generated dynamically rather than synced from static sources.

Configuration Reference

Field reference

repository

actions_permissions

branch_protection

contexts vs self_contexts

topics

pages

managed_files