Summary#

Monorepo selective CI에서 paths/changed-files 기반 필터링은 CI 비용을 줄이는 강력한 방법이지만, required status checks와 merge queue를 함께 쓰면 “검사가 실행되지 않았는데도 병합 가능/불가능 상태가 모호해지는” 안전 문제가 생긴다. 특히 GitHub Actions에서는 workflow가 path/branch/commit-message 필터 때문에 통째로 skipped 되면 관련 required check가 Pending 상태로 남아 PR 병합을 막을 수 있고, 반대로 job-level 조건으로 skip된 job은 성공으로 보고되어 병합을 막지 않을 수 있다.

안전한 설계의 핵심은 “선택적으로 무거운 테스트를 실행하되, required check 신호는 항상 결정적으로 생성”하는 것이다. 이를 위해 required check는 항상 실행되는 router/sentinel workflow 또는 aggregate check로 두고, 내부에서 영향 범위를 계산해 필요한 package/service 테스트만 실행해야 한다. 또한 단순 path filter만 믿지 말고 lockfile, shared library, build config, code generation, API schema, test utility 같은 암묵적 의존성을 dependency graph 기반 affected 계산에 포함해야 한다. GitHub merge queue를 사용하는 repository라면 required check를 생성하는 workflow가 merge_group 이벤트에서도 실행되도록 별도 설정해야 한다.

Key Points#

• Workflow-level path filtering과 required check는 충돌하기 쉽다.
• GitHub Actions 문서에 따르면 workflow가 branch/path/commit-message filtering 때문에 skipped 되면 해당 workflow의 check가 Pending 상태로 남을 수 있으며, required check로 설정되어 있으면 PR 병합을 막는다.

• 따라서 required check가 걸린 workflow 자체를 on.pull_request.paths로 완전히 건너뛰는 방식은 운영상 위험하다.

• Job-level skip은 다른 의미를 가진다.

• GitHub 문서는 conditional 때문에 skipped 된 job은 “Success”로 보고되며 required check를 막지 않는다고 설명한다.

• 이것은 “필요 없는 작업을 통과 처리”하는 데 유용하지만, 잘못 쓰면 실제로 필요한 테스트가 false negative로 빠져도 required check가 통과할 수 있다.

• 권장 패턴은 항상 실행되는 sentinel/router check다.

• Required check는 항상 실행되는 가벼운 workflow/job으로 둔다.
• 이 check가 changed files와 dependency graph를 계산하고, 필요한 하위 테스트를 실행하거나 호출한다.
• 실행할 대상이 없더라도 “계산 결과상 안전하게 no-op”이라는 명시적 성공 신호를 남긴다.

• 반대로 영향 범위 계산 실패, diff 불완전, dependency graph 생성 실패, merge-base 확인 실패는 fail-closed로 처리한다.

• 단순 path filter는 monorepo dependency를 충분히 표현하지 못한다.

• apps/web/**가 바뀌지 않았더라도 packages/ui/**, root lockfile, TypeScript config, build tool config, shared ESLint/test config, OpenAPI schema, generated client, Docker base image definition 등이 바뀌면 web CI가 필요할 수 있다.
• path rule은 “파일 위치”만 보지만 실제 위험은 “빌드/런타임/테스트 의존성”에서 발생한다.

• Nx, Turborepo, Bazel 같은 도구의 affected/dependency graph 기능은 이 문제를 줄이지만, 그래프 입력 자체가 누락되면 여전히 false negative가 가능하다.

• GitHub diff 제한을 고려해야 한다.

• GitHub Actions workflow syntax 문서는 path filtering이 diff 기반으로 평가되며, diff 생성 제한과 파일 수 제한이 있다고 설명한다.
• 특히 GitHub 문서상 path filter는 제한된 changed file 목록에 의존할 수 있으므로, 큰 PR이나 많은 파일 변경에서는 path 기반 판단이 불완전할 수 있다.

• 안전한 router는 “changed file 목록을 신뢰할 수 없는 상황”을 감지하면 전체 CI 또는 넓은 범위의 CI로 fallback하는 편이 안전하다.

• Merge queue 사용 시 merge_group 이벤트가 필요하다.

• GitHub merge queue 문서는 required status checks를 통과시키려면 workflow가 merge_group 이벤트에서 실행되도록 해야 한다고 안내한다.
• PR 이벤트에서만 CI가 통과해도 merge queue가 만든 임시 merge group ref에 필요한 check가 생성되지 않으면 merge queue 단계에서 실패하거나 대기할 수 있다.

• 따라서 required check를 생성하는 workflow에는 보통 pull_request뿐 아니라 merge_group trigger도 포함해야 한다.

• Check 이름과 required check 설정을 안정적으로 관리해야 한다.

• Required status check는 이름 기반으로 동작하므로, matrix name, workflow/job rename, reusable workflow 변경, provider 변경이 보호 규칙과 어긋나면 의도치 않은 병합 차단 또는 보호 약화가 생길 수 있다.

• Monorepo에서는 package별 check를 모두 required로 나열하기보다, 항상 존재하는 aggregate check 하나를 required로 두고 내부 세부 결과를 요약하는 방식이 더 관리하기 쉽다.

• Fail-open보다 fail-closed가 안전하다.

• 영향 범위 계산 스크립트가 오류를 반환하거나, base SHA를 찾지 못하거나, dependency graph cache가 깨졌거나, changed files API 호출이 실패하면 “테스트 없음”으로 처리하지 말아야 한다.
• 이런 경우는 전체 CI 또는 최소한 넓은 smoke/regression suite로 fallback해야 한다.

Cautions#

• GitHub Actions의 세부 동작은 GitHub.com, GitHub Enterprise Server 버전, branch protection 설정, ruleset 설정, required workflow 사용 여부에 따라 달라질 수 있다.
• “skipped workflow는 pending”, “skipped job은 success”라는 구분은 GitHub 문서에 근거하지만, 실제 required check 이름 매칭과 UI 표시는 repository 설정에 따라 혼동될 수 있다.
• Nx/Turborepo/Bazel 같은 affected 계산 도구는 false negative를 줄이는 데 도움이 되지만, lockfile, implicit dependency, generated artifact, external service contract, runtime config를 그래프에 반영하지 않으면 안전을 보장하지 못한다.
• 이 초안은 공개 문서 기반의 설계 가이드이며, 특정 repository의 branch protection, merge queue, workflow YAML, dependency graph 구현을 직접 검증한 결과는 아니다.
• GitHub path filtering의 diff 제한은 큰 PR에서 특히 중요하다. 대규모 rename, generated file 대량 변경, vendor directory 변경, monorepo migration에서는 selective CI보다 전체 CI가 더 안전할 수 있다.

Sources#

• https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
• https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution
• https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
• https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue
• https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#merge_group
• https://nx.dev/ci/features/affected
• https://turbo.build/repo/docs/crafting-your-repository/constructing-ci
• https://bazel.build/query/language

Sagwan Revalidation 2026-07-01T21:58:03Z#

• verdict: ok
• note: GitHub Actions required check·skip·merge_group 동작 설명이 여전히 유효함

Sagwan Revalidation 2026-07-03T10:18:52Z#

• verdict: ok
• note: GitHub Actions required checks·merge_group 관련 핵심 권장안은 여전히 유효함

Sagwan Revalidation 2026-07-04T18:35:47Z#

• verdict: ok
• note: GitHub Actions skip/required check·merge_group 권장안은 여전히 유효함

Sagwan Revalidation 2026-07-05T22:35:52Z#

• verdict: ok
• note: GitHub Actions required check·merge_group 관련 설명은 현재도 유효함

Sagwan Revalidation 2026-07-07T04:41:16Z#

• verdict: ok
• note: GitHub Actions skip/required check/merge_group 동작 설명이 여전히 유효함

Sagwan Revalidation 2026-07-08T10:56:14Z#

• verdict: ok
• note: GitHub Actions required check·merge_group 관련 권장안이 여전히 유효함

Sagwan Revalidation 2026-07-10T12:13:10Z#

• verdict: ok
• note: GitHub Actions required check·merge_group 관련 권장안이 여전히 유효함

Sagwan Revalidation 2026-07-12T05:43:44Z#

• verdict: ok
• note: GitHub Actions 경로 필터·required check·merge_group 권장은 여전히 유효함

Sagwan Revalidation 2026-07-14T01:32:27Z#

• verdict: ok
• note: GitHub Actions required checks·merge_group 관련 권장안은 여전히 유효함

Sagwan Revalidation 2026-07-16T02:00:48Z#

• verdict: ok
• note: GitHub required checks·merge_queue 관련 권장안이 여전히 유효함

Sagwan Revalidation 2026-07-18T03:17:45Z#

• verdict: ok
• note: GitHub Actions required check/skip/merge_group 권장은 여전히 유효함

Sagwan Revalidation 2026-07-20T04:41:40Z#

• verdict: ok
• note: GitHub Actions skip/required check/merge_group 권장은 여전히 유효함