設定參考

中央設定檔案驅動所有強制執行、同步和派發行為。它位於 docs-control 中的 .github/config/repo-settings.json，並在工作流程執行階段由下游儲存庫擷取。

{
  "_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": true,
        "contexts": [
          "Check linked issues",
          "lint / Lint Code Base",
          "lint / Shell Unit Tests"
        ],
        "self_contexts": ["Check linked issues", "Lint Code Base", "Shell Unit Tests"]
      },
      "required_pull_request_reviews": {
        "dismiss_stale_reviews": false,
        "require_code_owner_reviews": false,
        "required_approving_review_count": 0,
        "require_last_push_approval": false,
        "dismissal_restrictions": {
          "users": [],
          "teams": []
        },
        "bypass_pull_request_allowances": {
          "users": [],
          "teams": [],
          "apps": []
        }
      },
      "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": "f5-sales-demo/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": "workflows/antigravity-review.yml", "dest": ".github/workflows/antigravity-review.yml"},
      {"src": "workflows/antigravity-translate.yml", "dest": ".github/workflows/antigravity-translate.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": "AGENTS.md", "dest": "AGENTS.md"},
      {"src": ".agents/skills/demo-components/SKILL.md", "dest": ".agents/skills/demo-components/SKILL.md"},
      {"src": ".agents/skills/i18n-translate/SKILL.md", "dest": ".agents/skills/i18n-translate/SKILL.md"},
      {"src": ".editorconfig", "dest": ".editorconfig"},
      {"src": ".gitignore", "dest": ".gitignore"},
      {"src": "LICENSE", "dest": "LICENSE"},
      {"src": ".pre-commit-config.yaml", "dest": ".pre-commit-config.yaml"}
    ]
  }
}

欄位參考

`repository`

透過 PATCH /repos/{owner}/{repo} 套用的標準 GitHub 儲存庫設定。每個索引鍵直接對應到 GitHub API 欄位。強制執行工作流程會將每個索引鍵與儲存庫的目前值進行比較，並僅對已漂移的索引鍵進行修補。

值得注意的設定：

delete_branch_on_merge: true — 自動清理已合併的 PR 分支
allow_update_branch: true — 啟用 PR 上的「Update branch」按鈕
homepage: "" — 在執行階段自動計算為 https://f5-sales-demo.github.io/{repo}/

`actions_permissions`

控制儲存庫的 GitHub Actions 工作流程權限：

default_workflow_permissions: "write" — 工作流程預設取得儲存庫的讀取/寫入權限
can_approve_pull_request_reviews: true — 允許工作流程核准 PR

Antigravity 自動化控制

Configure Antigravity Controls 工作流程可變更控制 Antigravity 審查員與翻譯員的組織變數。每個階段都可以安全地重新執行：

disabled 將兩個變數均設定為 false，並具有 all 能見度。
pilot 將兩個變數均設定為 true，並將 selected 能見度限制為 docs-control。
all 僅在驗證了所選試點精確 HEAD 的審查收據和 12 個語言區域的翻譯發布之後，才將兩個變數均設定為 true 並具有 all 能見度。

該工作流程使用現有的治理個人存取權牌、受限的 GitHub API 重試和結構化的進度心跳。它不需要 GitHub App 或 GitHub Enterprise 功能。

`branch_protection`

分支保護規則陣列。每個項目指定一個 branch 名稱和所需的保護設定。目前僅保護 main。

關鍵欄位：

enforce_admins: true — 保護規則也套用到儲存庫管理員
required_status_checks.strict: true — 合併前分支必須是最新的
required_status_checks.contexts — 下游儲存庫必須通過的檢查名稱（例如 Check linked issues 和 lint / Shell Unit Tests）
required_status_checks.self_contexts — docs-control 本身必須通過的檢查名稱（例如 Check linked issues 和 Shell Unit Tests）
required_pull_request_reviews — 要求所有變更都必須透過 Pull Request 提交，同時 required_approving_review_count: 0 保持人工核準為選擇性；駁回和繞過清單保持為空
restrictions: null — 除分支保護外沒有推送限制

`contexts` 與 `self_contexts`

下游儲存庫中的可重用工作流程檢查使用 <caller_job_key> / <reusable_job_name>，而 docs-control 則報告其原始工作名稱。連結的 issue 關卡是一個例外：其排程工作流程會直接在每個儲存庫中發布認可狀態 Check linked issues，因此 contexts 和 self_contexts 都必須使用該確切名稱。

self_contexts 欄位儲存套用到 docs-control 本身的檢查名稱。在強制執行期間，工作流程會偵測它是否在來源儲存庫上執行，並在套用分支保護之前將 self_contexts 替換到 contexts 中。在將承載傳送到 GitHub API 之前，一律會移除 self_contexts 欄位。

Shell Unit Tests 是統一的儲存庫測試關卡。可重用工作流程一律會報告它：取用儲存庫會執行每個 tests/test-*.sh 檔案，而沒有符合測試的儲存庫則會報告成功並附帶明確的無測試訊息。這使得儲存庫 Shell 測試預設成為必需項目，而不是依賴每個儲存庫的選擇性加入清單。

取用者 Shell 測試設定檔

預設設定假設每個根目錄層級的 tests/test-*.sh 指令稿在未經設定的 GitHub 託管執行器上 salaried 都是密封（hermetic）的。在該萬用字元下同時儲存容器或服務整合測試的儲存庫需要在 repo-settings.json 中新增 consumer_shell_tests.profiles 項目。

每個設定檔對完整的符合清單進行分類：

unit 項目包含測試 path 和 args 陣列。執行器字面傳遞每個引數，不進行 Shell 評估。
environment 項目包含測試 path 和非空的 reason，解釋為什麼純執行器單元關卡無法執行它。

可重用工作流程從相同的 docs-control main 版本取得選取器和設定，記錄該版本，並在執行任何內容之前驗證清單。缺少設定、不安全的路徑或引數、重複的路徑以及未分類或缺失的測試將導致必需的快取內容失敗。這使設定檔成為經審計的分類契約，而不是忽略清單。沒有設定檔的儲存庫保持廣泛的預設設定。

xcsh 覆寫排除了兩個 Super-Linter 快取內容，因為該儲存庫不呼叫可重用的 Super-Linter 工作流程；其原生的 check、pii-guard 和 test 快取內容仍然是必需的。在新增排除項目之前，現場驗證必須證明排除是必要的。

不要要求具有 paths 或 paths-ignore 篩選工作流程中的快取內容。當工作流程未啟動時，GitHub 會保持該快取內容處於擱置狀態。廣泛的安全性工具必須在未篩選的拉取要求工作流程或排程的全樹審計中執行；受管理的工作流程安全性審計對 zizmor 使用後者模式。工作層級的條件是安全的，因為被略過的工作仍會報告成功的檢查。

`topics`

要套用到儲存庫的 GitHub 主題陣列。目前為空 — 不強制執行主題。

`pages`

GitHub Pages 設定：

enabled: true — 確保在每個註冊的儲存庫上都啟用了 Pages
build_type: "workflow" — 使用 GitHub Actions 進行 Pages 建置（而不是傳統的基於分支的建置）

`managed_files`

定義檔案同步清單：

source_repo — 保存受管理檔案規範版本的儲存庫 (f5-sales-demo/docs-control)
files — {src, dest} 物件的陣列，將 docs-control 中的來源路徑對應到下游儲存庫中的目標路徑

檔案同步工作流程會反覆運算此陣列以偵測並修正漂移。此處未列出的檔案（如 dependabot.yml 和 README.md）是動態產生的，而不是從靜態來源同步的。

設定參考

欄位參考

repository

actions_permissions

Antigravity 自動化控制

branch_protection

contexts 與 self_contexts