설정 적용

.github/workflows/enforce-repo-settings.yml에 위치한 적용 워크플로는 원하는 리포지토리 상태를 현재 상태와 비교하고 차이(드리프트)를 패치하는 재사용 가능하고 멱등적인 워크플로입니다. 다운스트림 리포지토리는 호출자 워크플로를 통해 이를 호출합니다. docs-control도 .github/config/repo-settings.json에 푸시할 때 직접 실행합니다.

트리거

• workflow_call — 다운스트림 호출자 워크플로에 의해 호출됨(6시간마다 예약됨, 구성 푸시 시 또는 수동 디스패치)
• push — docs-control의 main 브랜치에서 repo-settings.json이 변경될 때 실행됨

병렬 실행

설정 적용은 호출자에서 병렬 작업으로 실행되는 두 개의 재사용 가능한 워크플로로 분할되며, 각각 자체 최소 권한 토큰을 사용합니다.

• **enforce-repo-settings.yml**은 REPO_SETTINGS_TOKEN(Administration R/W, Pages R/W, Contents Read, Metadata Read)을 사용합니다.
• **sync-managed-files.yml**은 REPO_SYNC_TOKEN(Contents R/W, Issues R/W, Pull Requests R/W, Metadata Read)을 사용합니다.

이 페이지에서는 설정 적용 워크플로를 다룹니다. 관리 대상 파일 워크플로는 파일 동기화를 참조하세요.

7가지 단계

각 단계는 멱등성을 가집니다. 원하는 상태를 현재 상태와 비교하고 드리프트가 감지될 때만 변경합니다.

1단계: 검증 (Validate)

GitHub API를 통해 docs-control에서 중앙 구성을 가져옵니다(최대 5회 재시도). jq 및 gh를 사용할 수 있고 인증되었는지 검증합니다. 구성 값이 비어 있으면 homepage URL을 자동 계산합니다.

managed_files.source_repo와 github.repository를 비교하여 워크플로가 소스 리포지토리 자체에서 실행 중인지 감지합니다. 자체에서 실행 중인 경우 4단계를 위해 self_contexts 재정의가 활성화됩니다.

2단계: 리포지토리 설정 적용 (Apply repository settings)

GET /repos/{owner}/{repo}를 통해 repository 개체의 각 키를 리포지토리의 현재 설정과 비교합니다. 드리프트된 키만 포함하는 패치 개체를 빌드하고 PATCH /repos/{owner}/{repo}를 통해 적용합니다.

3단계: Actions 권한 적용 (Apply Actions permissions)

GET /repos/{owner}/{repo}/actions/permissions/workflow를 통해 actions_permissions 개체(기본 워크플로 권한, PR 검토 승인)를 현재 Actions 워크플로 권한과 비교합니다. 키가 드리프트된 경우 PUT을 통해 업데이트합니다.

4단계: 브랜치 보호 적용 (Apply branch protection)

branch_protection 배열을 순회합니다. 각 브랜치에 대해:

1. 자체에서 실행 중인 경우 self_contexts를 contexts로 교체합니다.
2. 페이로드에서 self_contexts를 제거합니다(GitHub API의 일부가 아님).
3. GET /repos/{owner}/{repo}/branches/{branch}/protection을 통해 현재 보호 규칙을 가져옵니다.
4. 비교 항목: enforce_admins, required_status_checks(strict + contexts), required_pull_request_reviews, restrictions 및 불리언 플래그(required_linear_history, allow_force_pushes, allow_deletions, block_creations, required_conversation_resolution, lock_branch, allow_fork_syncing)
5. 드리프트가 감지되면 PUT을 통해 보호 규칙을 생성하거나 업데이트합니다.

5단계: 토픽 적용 (Apply topics)

GET /repos/{owner}/{repo}/topics를 통해 topics 배열을 리포지토리의 현재 토픽과 비교합니다. 드리프트된 경우 PUT을 통해 교체합니다.

6단계: Pages 적용 (Apply Pages)

GET /repos/{owner}/{repo}/pages를 통해 GitHub Pages가 활성화되어 있는지 확인합니다. 찾을 수 없는 경우(404) 구성된 build_type으로 Pages를 활성화합니다. 찾았지만 build_type이 드리프트된 경우 PUT을 통해 업데이트합니다.

7단계: 검증 (Verify)

GitHub API를 통해 모든 설정을 다시 읽고 원하는 상태와 비교합니다. 리포지토리 설정, Actions 권한, 브랜치 보호(불리언 플래그 포함) 및 Pages 빌드 유형을 검증합니다. 적용 단계 후 일치하지 않는 설정이 있으면 워크플로가 실패합니다.

불변 워크플로 핀 롤포워드 (Immutable Workflow Pins Roll-Forward)

docs-control의 재사용 가능한 워크플로가 변경되면 .github/workflows/update-governed-workflow-pins.yml이 scripts/update-governed-workflow-pins.sh를 트리거하여 수동 개입 없이 호출자 워크플로 전체의 커밋 고정 SHA를 결정론적으로 업데이트합니다.