필수 상태 검사가 Expected에서 멈출 때 경로 필터와 merge queue 진단

문제 상황

필수 상태 검사로 지정한 build가 PR에서 Expected — Waiting for status to be reported로 멈춰 병합 버튼이 계속 회색이다. 재실행해도 변화가 없다.

전제 / 환경 (가상 예시)

• GitHub Actions, 기본 브랜치 main
• 브랜치 보호에서 build를 required status check로 지정
• merge queue(merge_group) 활성화

원인: 워크플로 전체 스킵 vs job if 스킵

두 가지를 반드시 구분한다.

• 워크플로 전체 스킵: on.pull_request.paths 필터에 안 맞으면 워크플로 자체가 실행되지 않는다. 이때 build 검사는 결과를 아예 보고하지 않아 영원히 Pending/Expected로 남는다.
• job if 스킵: 워크플로는 돌지만 if:로 job이 skipped 되면 그 skipped는 상태로 보고된다.

on:
  pull_request:
    paths:
      - 'src/**'   # docs만 바꾼 PR은 워크플로 자체가 안 돈다

docs만 수정한 PR은 build가 보고되지 않아 gate가 걸린다.

해결: 항상 도는 gate job

먼저 경로 필터를 제거해 테스트와 required 결과 보고를 분리한다. 아래 최소 예제는 문서만 바꿔도 테스트를 실행한다. 경로별 최적화보다 결과가 빠지지 않는 구성을 먼저 검증한다.

on:
  pull_request:
  merge_group:      # merge queue가 만든 검사도 트리거

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/test.sh   # 저장소에 맞게 교체

  build-gate:       # 이 이름을 required로 지정
    needs: [test]
    if: ${{ always() }}
    runs-on: ubuntu-latest
    steps:
      - name: 선행 결과 확인
        run: |
          if [ "${{ needs.test.result }}" != "success" ]; then
            echo "test=${{ needs.test.result }}"; exit 1
          fi

핵심:

• if: always()는 선행 job의 실패·스킵 때문에 gate가 자동 생략되는 것을 막는다. 워크플로 자체가 실행되지 않거나 전체 실행이 취소되는 상황까지 성공 결과를 보장하지 않는다.
• 그러나 needs.test.result를 검사해 failure/cancelled를 성공으로 넘기지 않는다. always()만 쓰고 결과 검사를 빼면 실패를 초록으로 덮는 꼼수가 되므로 금지.

merge queue 주의

merge queue를 켰다면 merge_group 트리거가 없는 워크플로는 큐 안에서 검사를 보고하지 않아 큐가 막힌다. required 검사 이름은 pull_request와 merge_group 양쪽에서 동일하게 나와야 한다.

검증 / 실패 판정

• docs만 바꾼 PR을 열고 build-gate가 success로 보고되는지 확인.
• test를 일부러 실패시키면 gate가 failure여야 한다. gate가 초록이면 결과 검사 로직이 잘못된 것.

경로별 최적화는 다음 단계에서

변경 감지 job을 추가한다면 그 job의 성공과 명시적인 테스트 불필요 판정을 함께 확인해야 한다. skipped를 무조건 허용하면 감지 실패나 잘못된 if도 통과시킬 수 있다. 위 gate는 success만 허용하므로 의도적인 skip도 실패로 처리한다.

PR 화면에서 현재 커밋 SHA, 실제 job 이름, required로 지정한 이름을 대조한다. 이전 커밋의 초록 체크나 다른 워크플로의 같은 이름을 현재 결과로 착각하지 않는다. merge queue에서도 큐가 만든 커밋에 검사 결과가 붙었는지 별도로 확인한다.

되돌리기 / 한계

• 새 워크플로에서 build-gate 실행 결과가 보고되는 것을 확인한 뒤 required 이름을 바꾼다. 되돌릴 때도 기존 워크플로와 기존 required 이름을 함께 복구한다. 존재하지 않는 검사 이름만 남기면 다시 병합이 막힌다.
• 이 방법은 "검사 보고 누락"을 막을 뿐, 테스트 품질 자체를 보장하지 않는다. 경로 필터가 복잡하면 어떤 job이 어떤 상태를 보고하는지 매트릭스로 문서화하는 편이 안전하다.

출처

• required status checks 문제 해결
• workflow syntax