온보딩

이 페이지에서는 docs-control 거버넌스 시스템에 새 리포지토리를 등록하고 문서 파이프라인 및 Antigravity AI 자동화를 구성하는 절차를 설명합니다.

사전 요구 사항

• f5-sales-demo 조직 구성원 자격
• REPO_SETTINGS_TOKEN 및 REPO_SYNC_TOKEN 시크릿이 조직 수준 시크릿으로 구성되어 있음(또는 새 리포지토리에 개별적으로 추가됨)
• 자동화된 Antigravity AI 코드 검토 및 언어 번역을 위해 구성된 ANTIGRAVITY_TOKEN 및 GCP_PROJECT_ID 시크릿
• ghcr.io/f5-sales-demo/docs-builder 컨테이너 이미지에 대한 액세스 권한

등록 단계

1. downstream-repos.json에 추가

docs-control의 .github/config/downstream-repos.json에 owner/repo 형식이 아닌 리포지토리의 단독 이름을 추가합니다. 소유자는 디스패치 시점에 GITHUB_REPOSITORY_OWNER로부터 앞에 붙습니다. 이를 통해 디스패치 및 적용 대상으로 등록됩니다.

그런 다음 .claude/governance.json의 repo_classes.repos에서 클래스를 할당합니다. 이는 필수 사항입니다. 클래스 할당 없이 리포지토리가 디스패치용으로 등록된 경우 셸 단위 테스트가 실패합니다.

2. docs-sites.json에 선택적 추가

리포지토리가 문서를 게시하는 경우 .github/config/docs-sites.json에 다음 항목을 추가합니다.

• label — 사람이 읽을 수 있는 사이트 이름
• url — 사이트의 llms-full.txt 엔드포인트 URL
• description — 생성된 README에서 사용되는 짧은 설명

항목이 추가되지 않은 경우 README 생성기는 대문자로 시작하는 리포지토리 이름과 GitHub API 설명으로 대체합니다.

3. .gitignore 통합

적용 워크플로는 다운스트림의 .gitignore를 완전히 덮어씁니다. 온보딩 전에 리포지토리 전용 항목을 docs-control의 템플릿 .gitignore에 병합하여 손실되지 않도록 하세요.

4. 호출자 워크플로 설치

docs-control의 workflows/에서 호출자 워크플로 템플릿을 새 리포지토리의 .github/workflows/ 디렉터리로 복사합니다.

• enforce-repo-settings.yml — 설정 적용 및 파일 동기화 트리거
• github-pages-deploy.yml — 문서 빌드 및 배포 트리거
• require-linked-issue.yml — PR과 이슈 연결 강제
• antigravity-review.yml — Antigravity AI PR 코드 검토 트리거
• antigravity-translate.yml — Antigravity AI 언어 번역 트리거
• super-linter.yml — PR에서 super-linter 제품군 실행
• dependabot-auto-merge.yml — 통과된 dependabot PR 자동 병합

이 파일들은 파일 동기화 워크플로에 의해 자동으로 동기화되지만, 수동으로 설치하면 프로세스가 부트스트랩됩니다.

5. 적용 트리거

새 리포지토리에서 설정 적용 워크플로를 수동으로 실행합니다.

source_sha=$(gh api repos/f5-sales-demo/docs-control/commits/main --jq '.sha')
gh workflow run enforce-repo-settings.yml \
  --repo f5-sales-demo/<repo-name> \
  -f source_sha="$source_sha"

이렇게 하면 모든 리포지토리 설정이 적용되고, 누락된 거버넌스 파일이 생성되며, 필요한 경우 동기화 PR이 생성됩니다.

6. 설정 검증

적용이 성공했는지 확인합니다.

gh run list --repo f5-sales-demo/<repo-name> --workflow enforce-repo-settings.yml --limit 1

브랜치 보호, Actions 권한 및 Pages가 올바르게 구성되었는지 확인합니다.

gh api repos/f5-sales-demo/<repo-name>/branches/main/protection \
  --jq '.required_status_checks.contexts'

7. 문서 사이트 검증

리포지토리에 docs/ 디렉터리가 있는 경우 첫 번째 성공적인 배포 후 문서 사이트에 액세스할 수 있는지 확인합니다.

curl -sf "https://f5-sales-demo.github.io/<repo-name>/" \
  && echo "OK" || echo "FAIL"

포크 충실도: 관리 대상 파일 옵트아웃

거버넌스 적용을 받는 대부분의 리포지토리는 모든 관리 대상 파일을 그대로 적용하지만, 활성 포크는 repo-settings.json의 managed_files 아래 skip_files 및 .claude/governance.json을 사용하여 특정 경로의 동기화를 옵트아웃할 수 있습니다.