Aplicação de Configurações

O fluxo de trabalho de aplicação em .github/workflows/enforce-repo-settings.yml é um fluxo de trabalho reutilizável e idempotente que compara o estado desejado do repositório com o estado atual e corrige qualquer desvio. Repositórios downstream o chamam através de um fluxo de trabalho chamador. O docs-control também o executa diretamente em pushes para .github/config/repo-settings.json.

Gatilhos

• workflow_call — invocado por fluxos de trabalho chamadores downstream (agendado a cada 6 horas, no push de config ou disparo manual)
• push — executado quando repo-settings.json é alterado na branch main do docs-control

Execução paralela

A aplicação é dividida em dois fluxos de trabalho reutilizáveis que executam como jobs paralelos no chamador, cada um com seu próprio token de privilégio mínimo:

• enforce-repo-settings.yml usa REPO_SETTINGS_TOKEN (Administração R/W, Pages R/W, Leitura de Conteúdo, Leitura de Metadados)
• sync-managed-files.yml usa REPO_SYNC_TOKEN (Conteúdo R/W, Issues R/W, Pull Requests R/W, Leitura de Metadados)

Esta página cobre o fluxo de trabalho de aplicação de configurações. Veja Sincronização de Arquivos para o fluxo de trabalho de arquivos gerenciados.

As 7 fases

Cada fase é idempotente: ela compara o estado desejado com o estado atual e faz alterações apenas quando um desvio é detectado.

Fase 1: Validar

Busca a configuração central do docs-control via API do GitHub (com 5 tentativas de repetição). Valida que jq e gh estão disponíveis e autenticados. Calcula automaticamente a URL da homepage se o valor de configuração estiver vazio.

Detecta se o fluxo de trabalho está sendo executado no próprio repositório de origem comparando managed_files.source_repo com github.repository. Se executado no próprio repositório, a substituição de self_contexts é ativada para a Fase 4.

Fase 2: Aplicar configurações de repositório

Compara cada chave no objeto repository com as configurações atuais do repositório via GET /repos/{owner}/{repo}. Constrói um objeto de patch contendo apenas as chaves que sofreram desvio e o aplica via PATCH /repos/{owner}/{repo}.

Fase 3: Aplicar permissões de Actions

Compara o objeto actions_permissions (permissões padrão do fluxo de trabalho, aprovação de revisão de PR) com as permissões atuais do fluxo de trabalho de Actions via GET /repos/{owner}/{repo}/actions/permissions/workflow. Atualiza via PUT se qualquer chave tiver sofrido desvio.

Fase 4: Aplicar proteção de branch

Itera sobre o array branch_protection. Para cada branch:

1. Se executado no próprio repositório, substitui self_contexts em contexts
2. Remove self_contexts do payload (não faz parte da API do GitHub)
3. Busca a proteção atual via GET /repos/{owner}/{repo}/branches/{branch}/protection
4. Compara: enforce_admins, required_status_checks (estrito + contextos), required_pull_request_reviews, restrictions e sinalizadores booleanos (required_linear_history, allow_force_pushes, allow_deletions, block_creations, required_conversation_resolution, lock_branch, allow_fork_syncing)
5. Cria ou atualiza regras de proteção via PUT se qualquer desvio for detectado

Fase 5: Aplicar tópicos

Compara o array topics com os tópicos atuais do repositório via GET /repos/{owner}/{repo}/topics. Substitui via PUT se houver desvio.

Fase 6: Aplicar Pages

Verifica se o GitHub Pages está habilitado via GET /repos/{owner}/{repo}/pages. Se não for encontrado (404), habilita o Pages com o build_type configurado. Se encontrado, mas o build_type tiver sofrido desvio, atualiza via PUT.

Fase 7: Verificar

Lê novamente todas as configurações via API do GitHub e as compara com o estado desejado. Verifica as configurações do repositório, permissões do Actions, proteção de branch (incluindo sinalizadores booleanos) e o tipo de build do Pages. Falha o fluxo de trabalho se qualquer configuração não coincidir após as fases de aplicação.

Avanço de Pinos de Fluxo de Trabalho Imutáveis

Quando fluxos de trabalho reutilizáveis no docs-control mudam, .github/workflows/update-governed-workflow-pins.yml dispara scripts/update-governed-workflow-pins.sh para atualizar SHAs fixados por commit em fluxos de trabalho chamadores de forma determinística e sem intervenção manual.