CI 개요¶
CI는 backend.tf를 표식으로 루트를 탐색하고
terraform-roots.json과 대조한다. 디렉터리 목록을 워크플로에 직접 쓰지 않는다.
루트별 PR 검사는 재사용 워크플로 _tf-root.yml에서 실행하고,
main 적용은 terraform-apply.yml의 반복문에서 실행한다.
.github/scripts/의 파일별 역할과 실행 방법은 CI 스크립트를 참고한다.
문서 구성¶
| 문서 | 확인할 내용 |
|---|---|
| PR plan과 코멘트 | job 의존성, matrix, plan 대상 선별, 결과 집계와 필수 검사 |
| Main apply | wave 순서, 종료 코드별 처리와 재실행 |
| KMS 검사 | KMS 변경 라벨, 키 관리·정책 검사 기준, 결과 누락 처리 |
| Rego 정책 | 자문·차단 규칙, 입력과 판정 결과, 규칙 작성·테스트 |
| 포맷 검사 | 실행 요건, 검사 대상과 규칙, 실패 처리와 편집기 연동 |
| 스크립트 | 파일별 역할, 입출력과 로컬 실행 방법 |
| 문서 CI와 Pages | 문서 변경 감지, strict 빌드, HTML 보관과 배포 조건 |
전체 흐름¶
flowchart TD
PR["PR 생성 또는 갱신"] --> Plan["terraform-plan.yml<br/>정적 검사, 대상 루트 plan, 코멘트"]
PR --> Docs["docs.yml<br/>문서 변경 감지 후 빌드"]
Plan --> Result["terraform plan / result"]
Docs --> Build["docs / build"]
Result --> Review["필수 검사 확인과 PR 리뷰"]
Build --> Review
Review --> Merge["main 병합"]
Merge --> ApplyFilter{"apply 대상 경로 변경?"}
ApplyFilter -->|예| Apply["terraform-apply.yml<br/>wave 순서대로 plan과 apply"]
ApplyFilter -->|아니오| SkipApply["자동 apply 생략"]
Merge --> DocsFilter{"문서 관련 경로 변경?"}
DocsFilter -->|예| MainDocs["문서 빌드와 docs-site 보관"]
DocsFilter -->|아니오| SkipDocs["문서 빌드 생략"]필수 검사로 설정할 이름은 terraform plan / result와 docs / build다.
Terraform PR 검사는 문서만 바뀌어도 실행하지만 변경 영향이 없는 루트의 plan은 생략하고,
문서 CI는 변경 감지 결과에 따라 빌드 스텝을 생략한다.
main apply와 문서 CI는 각각 수동 실행도 지원한다.
구성 파일의 역할¶
| 위치 | 책임 |
|---|---|
.github/workflows/ |
트리거, job 의존성, 권한, 변경 파일 조회, 코멘트 게시와 아티팩트 전달 |
.github/scripts/ |
루트 탐색, plan 대상 선별, AWS 정책 본문 검사, plan 요약과 apply 순서 본문 생성 |
.github/policy/ |
Terraform plan JSON에 대한 Rego 판정 규칙과 테스트 |
docs/ci/ |
CI 흐름과 각 구성 요소의 운영·개발 안내 |
루트 추가와 의존성¶
탐색 결과와 매니페스트 불일치, 잘못된 state key, 미등록 의존성, 순환 의존성은 CI를 실패시킨다. wave 개수는 의존 깊이에 맞춰 계산하며 고정 상한을 두지 않는다. 등록 절차와 매니페스트 형식은 저장소 구조에 있다.
로컬 검증¶
plan 대상 선별 테스트에는 terraform-config-inspect 설치가 필요하다.
npm run format:check는 Terraform과 JavaScript·JSON 포맷을 함께 검사한다.
실행 요건과 검사 대상은 포맷 검사에 있다.
npm ci --ignore-scripts
npm run format:check
node .github/scripts/test-tf-roots.js
node .github/scripts/test-tf-targets.js
node .github/scripts/tf-roots.js
node .github/scripts/test-validate-iam-policies.js
node .github/scripts/test-plan-summary.js
node .github/scripts/test-kms-summary.js
conftest verify --policy .github/policy
backend 없이 구성 문법을 확인하려면 각 루트에서 terraform init -backend=false와
terraform validate를 실행한다. CI의 validate job은 변경 영향이 있는 루트에만 이를 실행하며,
TF_PLUGIN_CACHE_DIR로 provider를 한 번만 받는다. 실제 AWS plan과는 검증 범위가 다르다.
액션은 커밋 SHA로 고정하고 Dependabot이 갱신한다.
actionlint 1.7.12는 GitHub가 지원하는 concurrency.queue를 아직 인식하지 못한다.
해당 버전으로 로컬 검사할 때는 공식 문법을 확인한 뒤 그 진단만 제외한다.
문서 워크플로 자체는 예외 없이 검사할 수 있다.