검증 게이트 및 자동화
개요
검증이 어디에 위치하며 어떻게 실제로 적용되는지에 대한 설명입니다. CI는 진실의 원천이며, 로컬 훅은 편의를 위한 미러입니다. 우회 불가능한 게이트로 강제되지 않은 규칙은 제안에 불과합니다 (원칙 7). 따라서 플랫폼이 해당 게이트를 제공할 수 없는 경우, 프로젝트는 advisory 모드를 선언하고, 없는 기계 장치를 가정하지 않은 채 규칙을 의도적으로 유지합니다.
규칙
- 하나의 작업 실행기가 모든 일상 작업의 표준 진입점입니다 — 테스트, 빌드, 개발, 배포는 명명된 레시피입니다. 누군가의 머릿속에만 있는 절차는 신뢰할 수 있게 발생하지 않으며 에이전트에게 전달할 수 없습니다.
- CI는 진실의 원천입니다 — 권위 있고, 공유되며, 플랫폼이 허용하는 모든 곳에서 우회 불가능합니다. 린트, 타입체크, 계약 검사, 테스트, 보안 스캔, 커밋 검증 모두 여기서 실행되며
enforced모드에서는 병합 전에 반드시 통과해야 합니다. CI가 말하는 것이 곧 사실입니다.advisory모드에서는 동일한 검사가 실행되고 보고되며, 게이트는 규율입니다. 이것이 검사를 줄일 이유가 되지는 않습니다. - 푸시 전 훅은 사전 제출 미러이지 장벽이 아닙니다. 동일한 빠른 검사를 로컬에서 실행하여 CI에 푸시하기 전에 아마도 통과할 수 있게 합니다. 명시적으로 우회 가능하며 (
--no-verify), 도구 체인이 설치된 경우에만 실행됩니다. 그 역할은 속도와 빠른 피드백이지 강제가 아닙니다. 훅은 게이트 역할을 하지 않으며, CI가 플랫폼이 허용하는 모든 곳에서 게이트 역할을 합니다. - 검사를 제거하지 말고 계층화하여 CI를 빠르게 유지하세요. 전체 테스트 스위트가 모든 PR에 비해 너무 커지면 presubmit(빠른 하위 집합, PR 차단)과 postsubmit(전체 스위트, 병합 후, 프로모션 차단)으로 분할하세요. 권위 있는 검사를 절대 우회 가능한 훅으로 옮기지 마세요.
- 컨테이너 이미지는 CI에서 빌드되며, 콘텐츠 다이제스트로 식별되고 출처 증명(provenance attestation)과 함께 게시됩니다. 레지스트리 레이어 캐싱이나 자체 호스팅 러너를 사용하여 비용을 감당 가능한 수준으로 유지하세요. 빌드를 다른 사람이 출처를 검증할 수 없는 랩탑으로 절대 옮기지 마세요.
- 강제 모드를 선언하세요.
enforced— CI가 브랜치 보호를 통해 병합을 차단합니다. CI가 말하는 것이 곧 사실입니다.advisory— CI가 실행되고 보고하며, 게이트는 규율입니다. 브랜치 보호를 사용할 수 없기 때문입니다 (무료 요금제의 비공개 리포지토리). Advisory는 합법적입니다. 가지고 있지 않은 강제를 주장하는 것은 그렇지 않습니다. 프로젝트의 첫 번째 결정 기록에 모드를 명시하고, 어떤 조건에서enforced로 전환할지 기술하세요.
명명된 긴장 관계
우회 가능한 로컬 사전 제출은 빠르지만 강제할 수 없습니다; 권위 있는 CI는 강제 가능하지만 느립니다. 각각에게 다른 임무를 부여하여 해결하세요. 훅은 내부 루프를 최적화하고, CI는 정확성의 기록을 담당합니다. 그리고 병합을 차단하는 것은 훅이 아니라 CI여야 합니다.
흔한 합리화
| 변명 | 현실 |
|---|---|
| "푸시 전 훅이 테스트를 실행하니까 CI는 최소한으로 해도 돼" | 훅은 우회 가능하고 도구 체인에 의존적입니다. 진실의 원천이 될 수 없습니다. CI는 모든 것을 다시 실행해야 합니다. |
"이번 한 번만 --no-verify 할게" | 괜찮습니다 — CI가 여전히 잡아낼 테니까요. 바로 그 이유로 게이트는 훅이 아니라 CI입니다. |
| "CI가 느리니까 테스트를 훅으로 옮기자" | CI를 계층화하고(presubmit/postsubmit), 권위 있는 검사를 우회 가능한 게이트로 옮기지 마세요. |
| "CI 빌드가 느려서 이미지를 로컬에서 빌드할게" | 랩탑에서 빌드된 아티팩트는 다른 누구도 출처를 검증할 수 없습니다. 레이어 캐시나 자체 호스팅 러너로 지연 시간을 해결하세요. |
| "브랜치 보호에 비용이 들으니까 규칙이 적용되지 않아" | 규칙은 적용됩니다. 강제 방식이 다를 뿐입니다. advisory 모드를 선언하고 규율을 유지하거나, 리포지토리를 공개로 전환하여 무료로 보호 기능을 얻으세요. |
위험 신호 — 중지
- 권위 있는 검사가 로컬 훅에만 존재하는 경우
- 훅이 실행한 검사를 CI가 다시 실행하지 않는 경우
- CI가 빨간색인데 병합이 허용되는 경우
- CI가 아닌 곳에서 이미지가 빌드되거나, 다이제스트 대신 태그로 프로모션되는 경우
- 브랜치 보호가 없는데 CI가 병합을 게이트한다고 행동하는 프로젝트
전체 근거: engineering-constitution/references/engineering-constitution.md에 번들된 헌법 제VIII조. 배포/k8s 세부사항: cloud-delivery-aks.