GitHub Actions 실패 로그 확인·검색·다운로드: 디버그 재실행까지 안전한 순서

GitHub Actions에 빨간 실패 표시가 떠도 곧바로 전체 재실행부터 누르지 마세요. 어느 작업의 어느 단계가 실패했는지, 같은 커밋을 다시 돌리는 것이 맞는지 먼저 확인해야 원인을 좁힐 수 있습니다. 아래는 로그 확인부터 검색·다운로드, 디버그 재실행까지 이어지는 공식 문서 기반 순서입니다.

빠른 결론

Actions에서 실패한 실행 → Job → 실패한 Step 순서로 로그를 엽니다.
Search logs는 펼쳐진 단계만 검색하므로 관련 단계를 먼저 확장하세요.
재실행은 원래 커밋과 ref를 사용합니다. 새 수정 커밋을 검사하려는 작업과 구분하세요.

확인 기준: 2026년 10월 2일, GitHub.com 웹 UI와 공식 GitHub Actions 문서. GitHub Enterprise Server 버전별 화면은 별도 확인이 필요합니다. 이 글은 실제 저장소를 변경하거나 테스트한 후기가 아닙니다.

확인 체크리스트

확인 항목	목적
실행 이름·커밋 SHA·브랜치	내가 조사하는 실행이 맞는지 확인
실패한 Job과 Step	실패 범위를 전체 워크플로와 구분
최초 오류와 그 앞뒤 출력	마지막 종료 코드만 보고 추측하지 않기
권한·재실행 영향	배포·외부 API 호출이 반복될지 확인
다운로드한 로그 공유 범위	민감 정보 노출 여부 검토

커밋 자체를 되돌려야 하는 문제라면 Git revert와 reset 차이를 먼저 보세요. 수정 커밋을 올리는 단계에서 푸시가 거부되면 Git push non-fast-forward 오류 점검을 확인하세요. 로컬 푸시 문제와 Actions runner의 실행 실패를 같은 원인으로 단정하지 마세요.

1. 실패한 단계의 로그 열기

1. GitHub에 로그인하고 저장소 메인 화면에서 Actions를 클릭합니다. 공개 저장소도 실행 정보를 보려면 로그인이 필요합니다.
2. 왼쪽 사이드바에서 대상 workflow를 선택하고 실행 목록에서 실패한 run 이름을 클릭합니다.
3. Jobs 또는 시각화 그래프에서 조사할 job을 클릭합니다.
4. 실패한 단계는 자동으로 펼쳐집니다. 오류 문장과 앞뒤 명령·환경 정보를 함께 읽습니다.
5. 팀에 특정 위치를 전달하려면 로그의 줄 번호를 클릭한 후 주소창 링크를 복사합니다.

로그 조회에는 저장소 읽기 권한이 필요합니다. 워크플로 파일에 적은 단계 외에도 GitHub가 Set up job, Complete job을 추가합니다. GitHub-hosted runner의 Set up job에는 runner 이미지 정보와 설치 도구 목록 링크가 있으므로 로컬과 다른 도구 버전을 조사할 때 참고하세요.

2. 검색하고 로그 파일 보관하기

1. 같은 job 화면에서 조사할 단계를 펼칩니다. 접힌 단계는 검색 결과에 포함되지 않습니다.
2. 로그 출력 오른쪽 위 Search logs 입력란에 오류 코드, 실패한 파일명, 명령어 등 실제 출력에 있던 단어를 입력합니다.
3. 결과가 없으면 오탈자보다 먼저 단계가 펼쳐져 있는지, 다른 job을 보고 있지 않은지 확인합니다.
4. 로그 오른쪽 위 드롭다운 메뉴에서 Download log archive를 선택해 아카이브를 내려받습니다.

로그 다운로드와 build artifact 다운로드는 다른 작업입니다. 설치 결과물이나 보고서가 필요하다면 artifact를 별도로 확인하세요. 원인 조사 중 Delete all logs를 누르면 조사 자료가 사라질 수 있으므로 이 가이드에서는 삭제를 권하지 않습니다.

3. 필요한 범위만 디버그 재실행하기

1. 실행 요약으로 돌아가 오른쪽 위 Re-run jobs 드롭다운을 엽니다.
2. 실패한 작업을 다시 조사하려면 Re-run failed jobs, 전체를 다시 실행해야 할 이유가 있으면 Re-run all jobs를 선택합니다.
3. 추가 진단 정보가 필요하면 확인 화면의 Enable debug logging을 선택합니다.
4. 배포·알림·데이터 쓰기 등 반복 실행의 영향을 검토한 후 Re-run jobs로 확정합니다.
5. 완료 후 같은 job의 로그를 비교하고 실행 이름 오른쪽 Latest 드롭다운에서 이전 attempt도 확인합니다.

재실행은 재실행 버튼을 누른 사람 대신 최초 실행을 유발한 actor의 권한을 사용하고, 원래 이벤트의 GITHUB_SHA와 GITHUB_REF를 그대로 사용합니다. 수정한 새 커밋을 이 버튼으로 자동 검사한다고 생각하지 마세요. 한 실행은 전체·부분 재실행 합계 최대 50회까지 재실행할 수 있습니다.

추가 진단과 막힐 때 확인할 것

지속적으로 runner 진단이 필요하면 저장소 secret 또는 variable ACTIONS_RUNNER_DEBUG를 true로 설정하는 공식 방법이 있습니다. 아카이브의 runner-diagnostic-logs 폴더에 runner·worker 프로세스 로그가 추가됩니다. 단계의 자세한 출력은 ACTIONS_STEP_DEBUG=true로 늘릴 수 있습니다. 같은 이름의 secret과 variable을 함께 설정하면 secret 값이 우선합니다.

• 설정 생성 권한은 저장소·조직·환경에 따라 다릅니다. 버튼이 안 보인다고 워크플로 오류로 단정하지 말고 권한과 실행 상태를 관리자에게 확인하세요.
• 디버그 출력은 더 자세합니다. 토큰·개인 정보·내부 주소가 포함될 가능성을 검토한 후 필요한 부분만 공유하고, 비밀 값을 echo하는 진단 코드는 넣지 마세요.
• 재실행이 다시 실패하면 같은 단계의 최초 오류, runner 도구 정보, 실행 attempt를 함께 남기세요. 무한 반복 재실행은 원인 해결을 대신하지 못합니다.
• CLI 사용자는 gh run view RUN_ID --log로 로그를 보고, gh run rerun RUN_ID --failed --debug로 실패 작업의 디버그 재실행을 요청할 수 있습니다. 실제 ID와 대상 저장소를 확인한 뒤 사용하세요.

FAQ 3

Q1. Search logs에서 오류가 안 나오면 로그가 없는 건가요?

아닙니다. 공식 문서상 검색은 펼쳐진 단계만 포함합니다. 실패한 job이 맞는지 확인하고 관련 단계를 확장한 뒤 검색하세요. 필요하면 아카이브를 내려받아 비교합니다.

Q2. 새 커밋을 푸시한 뒤 기존 실패 실행을 재실행하면 새 코드가 검사되나요?

기존 재실행은 원래 GITHUB_SHA와 GITHUB_REF를 사용합니다. 새 수정 사항 검증은 그 커밋을 대상으로 생성된 실행인지 확인해야 합니다. 재실행 결과를 새 코드의 결과로 혼동하지 마세요.

Q3. 디버그 로그를 켜려면 반드시 secret을 만들어야 하나요?

재실행 확인 화면의 Enable debug logging도 runner 진단과 step 디버그를 활성화하는 공식 경로입니다. 지속 설정은 secret 또는 variable을 사용할 수 있으며 생성 권한 조건을 확인해야 합니다.

공식 출처

워크플로 실행 로그 사용 · 워크플로·job 재실행 · 디버그 로그 활성화

화면·정책 변경 시 공식 문서를 우선하세요. 원인 미확인 상태에서 저장소의 권한·secret·배포 설정을 임의로 변경하지 않는 것이 안전합니다.