CI(지속적 통합) 파이프라인이 붉은 X 표시로 멈췄을 때, 개발자가 가장 먼저 부딪히는 벽은 '왜 실패했는지'를 손에 잡히게 확인하기 어렵다는 점이다. 로그는 수백 줄에 달하고, 실제 원인 한 줄은 뒤따르는 잡음에 묻힌다. 로컬 환경은 CI와 미묘하게 달라서 '내 컴퓨터에서는 되는데'라는 상황이 반복된다. FailTrace는 바로 이 간극을 좁히려는 오픈소스 명령줄 도구다. 실패한 GitHub Actions 실행의 URL 하나를 붙여넣으면, 어느 잡(job)과 스텝(step)이 깨졌는지 찾아내고 해당 커밋 시점의 워크플로 파일과 대조한 뒤, 로그에서 실패 지점을 추려 '로컬에서 똑같이 실패하게 만들려면 무엇이 필요한지'까지 알려준다.
비슷한 범주의 도구인 act가 워크플로 자체를 로컬에서 실행하는 데 초점을 둔다면, FailTrace는 질문 자체가 다르다. '이 특정 실행은 왜 실패했고, 그 실패를 내 기기에서 동일하게 재현할 수 있는가'를 묻는다. 예컨대 prometheus/prometheus의 실패 사례에서 로그 말미가 go.sum 차이로 수백 줄 채워져 있을 때, FailTrace는 첫 번째 오류 줄을 중심으로 발췌를 정렬해 go mod tidy가 go.mod를 바꿨다는 진짜 원인을 그 이후의 소음보다 먼저 보여준다.
세 개의 명령으로 나뉜 단계
도구는 아직 초기 개발 단계지만 세 개의 명령이 모두 동작한다. 첫 단계는 분석이다. 실행 컨텍스트(워크플로, 이벤트, 브랜치, 커밋, 시도 횟수)를 보여주고, 실패한 잡을 워크플로 정의와 매핑한다. 이때 test (ubuntu-latest, 1.22)나 Lint ${{ matrix.tool }}처럼 매트릭스 값이 포함된 잡 이름도 식별하고 그 값을 복원한다. 요청된 러너 라벨과 로그에서 추출한 실제 러너 이미지·버전, 실패한 스텝의 정의(run, uses, with, env, shell, 작업 디렉터리)도 함께 제시한다. 진단 단계에서는 종료 코드와 오류 주석, 실패한 테스트 이름을 뽑아내는데 Go, pytest, Jest, Vitest, Cargo, RSpec을 지원한다. 또한 서비스 컨테이너, 잡 컨테이너, 스텝이 쓰는 시크릿, 재사용 워크플로, macOS·Windows 러너처럼 로컬 재현을 어렵게 만드는 요소를 '재현 노트'로 정리한다. 잡이 시작되기도 전에 실패한 경우나 저장소에 파일이 없는 동적 워크플로, 만료된 로그 같은 예외 상황도 조용히 실패하는 대신 설명해 준다.
plan 명령은 실제로 아무것도 실행하지 않은 채 재현 계획만 출력한다. 여기서 나오는 판정(verdict)은 세 가지다. 빠진 것이 없으면 ready, 실행은 되지만 일부가 근사치이거나 누락되면 partial, 실패한 스텝이 스크립트가 아니라 액션이라 아직 재생할 수 없으면 blocked이다. setup-go, setup-node, setup-python, setup-java, setup-dotnet, ruby/setup-ruby, dtolnay/rust-toolchain, pnpm 계열, astral-sh/setup-uv, oven-sh/setup-bun, denoland/setup-deno 등 주요 설정 액션을 지원한다.
Docker 안에서 CI 환경을 복제한다
repro 명령은 계획을 세운 뒤 Docker로 실행하고 그 결과를 CI의 실패와 비교한다. Docker와 git이 필요하다. stretchr/testify에서 go vet이 Go oldstable로 실패한 사례를 보면, FailTrace는 oldstable을 CI가 쓴 정확한 Go 1.26.9 빌드로 해석하고, CI가 테스트한 PR 병합 커밋을 체크아웃한 뒤 스텝을 재생했다. 환경 이미지는 계획의 베이스 이미지에 모든 우분투 러너가 갖춘 패키지(git, curl, 빌드 도구, python3, jq, sudo 등)와 툴체인을 더해 구성된다. Go·Node·Python은 setup 액션이 내려받는 것과 동일한 빌드를 CI가 쓰는 /opt/hostedtoolcache 경로에 설치하며, 이미지는 내용 해시로 태그되어 환경당 한 번만 빌드된다. 워크스페이스는 actions/checkout과 같은 방식·같은 패치 깊이로 정확한 커밋을 가져와 러너와 동일한 경로에 마운트하고, GitHub가 PR 병합 커밋을 교체했다면 로컬에서 병합을 다시 만든다. 서비스 컨테이너는 잡 컨테이너의 네트워크 네임스페이스에서 시작돼 localhost:5432와 postgres:5432가 모두 동작하도록 하고 헬스 체크를 기다린다.
실무적으로 주목할 만한 부분은 플래키(flaky) 테스트 처리다. 설정 스텝은 한 번만 실행되고 실패한 스텝만 같은 컨테이너에서 N회 반복되므로 반복 비용이 싸다. 어떤 때만 실패하면 '10회 중 3회 실패' 같은 flaky 판정이 나온다. 이때 Go의 테스트 캐시는 GOFLAGS=-count=1로 우회하는데, 그러지 않으면 캐시된 통과 결과가 재생되어 간헐적 실패를 숨기기 때문이다. 실행이 끝난 뒤 --shell을 쓰면 실패한 스텝이 돌던 자리(같은 디렉터리·환경·툴체인·서비스)에서 셸이 열리고 스텝을 다시 돌리는 명령이 출력된다. --report는 판정과 CI 대 로컬 비교표, 환경, 차이점, 각 스텝 결과, 양쪽의 실패 스텝 출력을 담은 마크다운 보고서를 만들어 이슈나 PR에 붙여넣기 좋게 한다.
아키텍처 차이와 안전성
한계도 분명하다. --platform을 지정하지 않으면 잡은 CI와 같은 linux/amd64로 실행되는데, 애플 실리콘 맥에서는 이것이 에뮬레이션을 의미한다. 같은 재현이 40초 대신 약 9분 걸렸고 판정은 동일했다는 예가 그 비용을 잘 보여준다. 또한 현재 repro가 다루는 범위는 실패 스텝이 run: 스크립트인 리눅스 잡으로 제한된다. 모든 판정에는 CI와 알려진 차이 목록이 함께 붙어, 재현 결과를 어디까지 신뢰할지 스스로 판단하게 한다.
보안 측면에서 repro는 PR의 코드를 포함해 저장소의 코드를 사용자 기기의 컨테이너 안에서 실행한다는 점을 짚어 둘 필요가 있다. 컨테이너는 워크스페이스만 볼 수 있고 홈 디렉터리나 Docker 소켓에는 접근하지 못하며, --secret NAME으로 명시적으로 넘기지 않는 한 어떤 시크릿도 주어지지 않는다. 그 값은 환경 변수에서 읽어 들여 셸 히스토리나 프로세스 목록에 노출되지 않는다. 다만 공개 저장소라도 로그 API가 토큰을 요구하기 때문에 GitHub 토큰이 반드시 필요하고, 비공개 저장소는 Actions 읽기 권한이 있는 토큰을 써야 한다. 신뢰할 수 없는 PR 코드를 재현할 때는 결국 로컬에서 실행해도 괜찮은 코드인지 사용자가 직접 판단해야 한다는 전제를, 도구는 설계상 분명히 하고 있다.