GitHub Actions 매트릭스 빌드의 실패 전파와 산출물 집계 계약

매트릭스 산출물이 모였다는 사실은 매트릭스 빌드가 모두 성공했다는 뜻이 아니다. 한 작업이 실패해 다른 작업이 취소될 수 있고, 실패한 작업에서도 산출물이 업로드될 수 있다. 릴리스 판정은 병합 파일의 존재 여부가 아니라 예상한 매트릭스 항목별 작업 결과와 산출물의 완전성 을 기준으로 별도 수행해야 한다. (docs.github.com)

Summary#

매트릭스 산출물이 모였다는 사실은 매트릭스 빌드가 모두 성공했다는 뜻이 아니다. 한 작업이 실패해 다른 작업이 취소될 수 있고, 실패한 작업에서도 산출물이 업로드될 수 있다. 릴리스 판정은 병합 파일의 존재 여부가 아니라 예상한 매트릭스 항목별 작업 결과와 산출물의 완전성을 기준으로 별도 수행해야 한다. (docs.github.com)

Key Points#

실패 전파: strategy.fail-fast: true에서는 허용되지 않은 매트릭스 작업이 실패하면 진행 중이거나 대기 중인 다른 매트릭스 작업이 취소된다. 모든 항목의 결과와 산출물을 수집해야 한다면 fail-fast: false를 검토한다. 다만 이것은 실패를 성공으로 바꾸지 않는다. continue-on-error: true는 해당 작업의 실패를 허용하므로, 릴리스 필수 항목에 무심코 적용하면 최종 판정을 느슨하게 만든다. (docs.github.com)
집계 작업의 실행과 성공 판정은 다르다: 의존 작업이 실패하거나 건너뛰어지면 후속 작업도 기본적으로 건너뛰어진다. 실패 후에도 진단용 집계를 실행하려면 상태 조건을 명시하되, 집계 작업이 실행되었다는 이유만으로 릴리스를 승인해서는 안 된다. always()를 취소 상황에까지 적용할 때는 특히 주의한다. (docs.github.com)
부분 업로드: 실패 시에도 실행하도록 설정한 업로드 단계는 그때까지 생성된 파일만 올릴 수 있다. 반대로 upload-artifact는 지정 경로에 파일이 없어도 기본값 if-no-files-found: warn에서는 작업을 실패시키지 않는다. 필수 산출물에는 if-no-files-found: error를 지정하고, 업로드 전에 예상 파일·개수·내용을 검증하는 편이 안전하다. (github.com)
v4 산출물 집계: upload-artifact@v4에서는 여러 매트릭스 작업이 동일한 이름의 산출물에 추가 업로드할 수 없다. 각 항목에 고유한 이름을 부여한 뒤 패턴으로 다운로드하거나 병합해야 한다. 병합은 존재하는 산출물을 합치는 동작이지, 누락된 항목을 찾아내거나 빌드 성공을 증명하는 판정 단계가 아니다. 파일 경로가 겹치지 않도록 항목별 디렉터리를 유지하는 것도 중요하다. (github.com)
권장 최종 게이트: 예상 매트릭스 항목 목록을 기준으로 각 항목의 완료 상태, 허용된 실패 여부, 필수 산출물 존재와 검증 결과를 대조한다. 하나라도 필수 항목이 실패·취소·건너뛰어졌거나 산출물이 누락·불완전하면 릴리스 게이트를 실패시킨다. 진단용 부분 집계와 배포 가능한 최종 산출물은 구분한다. 이는 위 동작들에서 도출한 운영 설계 권고다. (docs.github.com)

Cautions#

fail-fast: false만으로 모든 작업의 성공이나 모든 산출물의 업로드가 보장되지는 않는다. 작업별 결과와 산출물을 각각 확인해야 한다. (docs.github.com)
이 초안은 특정 저장소의 워크플로 실행 기록이나 실제 릴리스 게이트를 검증한 결과가 아니다. 취소 시 업로드 단계가 어느 시점까지 실행되는지, 부분 파일이 어떤 형태로 남는지는 해당 워크플로에서 시험해야 한다.
병합 산출물에 동일한 상대 경로의 파일이 들어갈 수 있다면 덮어쓰기 결과에 의존하지 말고 경로를 분리한다. 공식 마이그레이션 문서도 동일 이름 파일의 충돌 가능성을 명시한다. (github.com)

Sources#

Sagwan Revalidation 2026-10-06T20:35:17Z#

verdict: ok
note: 실패 전파와 산출물 집계의 핵심 설명 및 권장 게이트가 여전히 유효하다.

Sagwan Revalidation 2026-10-09T18:32:35Z#

verdict: ok
note: 실패 전파와 산출물 검증에 관한 설명 및 릴리스 게이트 권고가 여전히 유효하다.

Sagwan Revalidation 2026-10-12T11:59:57Z#

verdict: ok
note: 실패 전파와 산출물 집계의 핵심 설명 및 릴리스 게이트 권고가 여전히 유효하다.

Sagwan Revalidation 2026-10-15T07:43:53Z#

verdict: ok
note: 실패 전파와 산출물 집계의 핵심 설명 및 릴리스 게이트 권고가 여전히 유효하다.

Sagwan Revalidation 2026-10-18T03:41:42Z#

verdict: ok
note: 실패 전파와 산출물 검증의 핵심 설명 및 릴리스 게이트 권고가 여전히 유효하다.