GitHub Actions matrix 빌드에서 한 조합만 랜덤하게 실패하는 이유

문제 발생

Node 버전 3개 x OS 2개, 총 6개 조합으로 matrix 빌드를 돌리는데, 그중 한 조합만 가끔씩(항상은 아니고) 테스트가 실패했습니다. 로컬에서는 재현되지 않았습니다.

strategy:
  matrix:
    node: [20, 22, 24]
    os: [ubuntu-latest, windows-latest]

원인 분석

matrix의 각 조합은 기본적으로 독립된 러너에서 병렬 실행되므로, 조합 자체가 서로 다른 러너 인스턴스를 공유하지는 않습니다. 그런데도 간헐적 실패가 난다면, 흔한 원인은 다음과 같습니다.

1. 테스트가 실제 외부 자원(DB, 파일, 포트)을 공유: 같은 워크플로우 안의 다른 job이나 같은 job의 여러 테스트 파일이 같은 포트, 같은 임시 파일 경로, 같은 DB 스키마를 동시에 쓰면 병렬 실행 시 충돌합니다.
2. 타이밍에 의존하는 테스트: 네트워크 지연이나 CPU 성능이 로컬과 다른 CI 러너에서는 setTimeout에 의존한 테스트나 비동기 순서를 가정한 테스트가 예상과 다르게 동작할 수 있습니다. 특정 OS(예: Windows)가 유독 느리거나 파일 시스템 동작이 달라 그 조합에서만 재현되는 경우가 흔합니다.
3. 테스트 실행 순서에 의존하는 상태 공유: 테스트 프레임워크가 병렬로 테스트 파일을 실행할 때, 전역 상태나 시드 데이터를 공유하면 실행 순서가 매번 달라져 특정 조합에서만 우연히 겹치는 순서가 나올 수 있습니다.

해결 방안

1. 테스트가 DB 같은 공유 자원을 쓴다면, 테스트 파일마다 독립된 스키마/네임스페이스를 쓰거나 각 테스트가 자기가 만든 데이터만 정리하도록 격리합니다.
2. 타이밍에 의존하는 테스트는 고정된 sleep 대신 실제 상태를 폴링하거나 콜백/이벤트 기반으로 대기하도록 바꿉니다.
3. 실패한 조합만 재현하고 싶다면 workflow_dispatch로 해당 matrix 조합만 수동 실행하거나, 로그의 실행 시각/순서를 비교해 공유 자원 경쟁 여부를 먼저 확인합니다.
4. 정말 원인을 못 찾는 flaky 테스트는 재시도(retry) 액션으로 임시 완화할 수 있지만, 이는 근본 원인을 숨기는 것이므로 별도 이슈로 남겨 추적해야 합니다 — 계속 방치하면 "실패해도 재시도하면 되니까 무시"하는 습관이 진짜 회귀를 놓치게 만듭니다.

공식 문서

• GitHub Actions Docs: Using a matrix for your jobs