Riferimento di configurazione

Il file di configurazione centrale guida tutto il comportamento di applicazione, sincronizzazione e dispatch. Si trova in .github/config/repo-settings.json in docs-control ed è recuperato dai repository a valle durante l’esecuzione del workflow.

{
  "_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"}
    ]
  }
}

Riferimento dei campi

`repository`

Impostazioni standard del repository GitHub applicate tramite PATCH /repos/{owner}/{repo}. Ogni chiave si mappa direttamente al campo dell’API GitHub. Il workflow di applicazione confronta ciascuna chiave con il valore attuale del repository e applica la patch solo alle chiavi che hanno subito una deviazione.

Impostazioni rilevanti:

delete_branch_on_merge: true — elimina automaticamente i branch delle PR unite
allow_update_branch: true — abilita il pulsante “Update branch” sulle PR
homepage: "" — calcolato automaticamente al momento dell’esecuzione come https://f5-sales-demo.github.io/{repo}/

`actions_permissions`

Controlla i permessi dei workflow di GitHub Actions per il repository:

default_workflow_permissions: "write" — i workflow ottengono l’accesso in lettura/scrittura al repository per impostazione predefinita
can_approve_pull_request_reviews: true — consente ai workflow di approvare le PR

Controlli di automazione Antigravity

Il workflow Configure Antigravity Controls modifica le variabili dell’organizzazione che regolano il revisore e il traduttore Antigravity. Ogni fase è sicura da rieseguire:

disabled imposta entrambe le variabili su false con visibilità all.
pilot imposta entrambe le variabili su true con visibilità selected limitata a docs-control.
all imposta entrambe le variabili su true con visibilità all solo dopo aver convalidato la ricevuta di revisione exact-head del pilota selezionato e la pubblicazione della traduzione in 12 lingue.

Il workflow utilizza il token di accesso personale di governance esistente, tentativi limitati dell’API GitHub e battiti cardiaci di avanzamento strutturati. Non richiede un’app GitHub o funzionalità GitHub Enterprise.

`branch_protection`

Un array di regole di protezione dei branch. Ogni voce specifica un nome di branch e le impostazioni di protezione desiderate. Attualmente solo main è protetto.

Campi chiave:

enforce_admins: true — le regole di protezione si applicano anche agli amministratori del repository
required_status_checks.strict: true — i branch devono essere aggiornati prima dell’unione
required_status_checks.contexts — i nomi dei controlli che i repository a valle devono superare (ad esempio, Check linked issues e lint / Shell Unit Tests)
required_status_checks.self_contexts — i nomi dei controlli che docs-control stesso deve superare (ad esempio, Check linked issues e Shell Unit Tests)
required_pull_request_reviews — richiede che tutte le modifiche entrino tramite una pull request mentre required_approving_review_count: 0 mantiene l’approvazione umana opzionale; le liste di licenziamento e bypass rimangono vuote
restrictions: null — nessuna restrizione di push oltre alla protezione del branch

`contexts` rispetto a `self_contexts`

I controlli dei workflow riutilizzabili nei repository a valle utilizzano <caller_job_key> / <reusable_job_name>, mentre docs-control segnala i relativi nomi di job semplici. Il gate dei ticket collegati fa eccezione: il suo workflow pianificato pubblica lo stato del commit Check linked issues direttamente in ogni repository, pertanto sia contexts che self_contexts devono utilizzare quel nome esatto.

Il campo self_contexts memorizza i nomi dei controlli che si applicano a docs-control stesso. Durante l’applicazione, il workflow rileva se è in esecuzione sul repository di origine e sostituisce self_contexts in contexts prima di applicare la protezione del branch. Il campo self_contexts viene sempre rimosso prima di inviare il payload all’API GitHub.

Shell Unit Tests è il gate di test uniforme del repository. Il workflow riutilizzabile lo segnala sempre: i repository consumatori eseguono ogni file tests/test-*.sh, mentre un repository senza test corrispondenti segnala il successo con un messaggio esplicito di assenza di test. Ciò rende i test shell del repository obbligatori per impostazione predefinita anziché fare affidamento su elenchi di adesione per repository.

Profili di test shell del consumatore

L’impostazione predefinita presuppone che ogni script tests/test-*.sh a livello root sia ermetico su un runner ospitato su GitHub non configurato. Un repository che memorizza anche test di integrazione di container o servizi sotto quel glob necessita di una voce consumer_shell_tests.profiles in repo-settings.json.

Ogni profilo classifica l’inventario corrispondente completo:

Le voci unit contengono un path di test e un array args. Il runner passa ogni argomento letteralmente, senza valutazione shell.
Le voci environment contengono un path di test e un motivo reason non vuoto che spiega perché il gate unitario del runner semplice non può eseguirlo.

Il workflow riutilizzabile recupera il selettore e la configurazione dalla stessa revisione main di docs-control, registra tale revisione e convalida l’inventario prima di eseguire qualsiasi cosa. Configurazione mancante, percorsi o argomenti non sicuri, percorsi duplicati e test non classificati o mancanti fanno fallire il contesto richiesto. Ciò rende un profilo un contratto di classificazione controllato anziché un elenco da ignorare. I repository senza un profilo mantengono l’impostazione predefinita generale.

L’override di xcsh esclude entrambi i contesti Super-Linter perché quel repository non chiama il workflow riutilizzabile Super-Linter; i suoi contesti nativi check, pii-guard e test rimangono obbligatori. La verifica dal vivo deve dimostrare che un’esclusione è necessaria prima di essere aggiunta.

Non richiedere un contesto da un workflow con filtri paths o paths-ignore. GitHub lascia quel contesto in sospeso quando il workflow non si avvia. Gli strumenti di sicurezza generali devono essere eseguiti in un workflow di pull request non filtrato o in un audit completo pianificato dell’albero; l’audit di sicurezza del workflow gestito utilizza quest’ultimo modello per zizmor. Una condizione a livello di job è sicura poiché un job ignorato segnala comunque un controllo riuscito.

`topics`

Un array di argomenti GitHub da applicare al repository. Attualmente vuoto — gli argomenti non sono applicati.

`pages`

Configurazione di GitHub Pages:

enabled: true — assicura che Pages sia abilitato in ogni repository iscritto
build_type: "workflow" — utilizza GitHub Actions per la build di Pages (non build obsolete basate su branch)

`managed_files`

Definisce il manifesto di sincronizzazione dei file:

source_repo — il repository che contiene le versioni canoniche dei file gestiti (f5-sales-demo/docs-control)
files — un array di oggetti {src, dest} che mappano i percorsi di origine in docs-control sui percorsi di destinazione nei repository a valle

Il workflow di sincronizzazione dei file esegue un’iterazione su questo array per rilevare e correggere le deviazioni. I file non elencati qui (come dependabot.yml e README.md) vengono generati dinamicamente anziché sincronizzati da origini statiche.

Riferimento di configurazione

Riferimento dei campi

repository

actions_permissions

Controlli di automazione Antigravity

branch_protection

contexts rispetto a self_contexts