바로 답변 GitHub Actions에서 배포가 실패했을 때는 로그를 많이 보는 것보다 순서를 잘 잡는 것이 더 중요합니다. 제일 먼저 볼 로그 3개만 고르면 아래입니다.

1) 실패한 step의 원문 로그 가장 먼저 봐야 하는 건 빨갛게 실패한 딱 그 step의 펼친 로그입니다. 여기서 먼저 확인할 수 있는 게 많습니다.

• 어떤 명령어가 실제로 실행됐는지
• 어느 줄에서 종료됐는지
• 에러가 build 실패인지, 권한 실패인지, 환경변수 누락인지
• 종료 코드가 1인지, 127인지, 타임아웃인지

예를 들어:

• npm run build에서 죽었으면 애플리케이션 빌드 문제일 가능성이 큽니다.
• Permission denied면 배포 키나 토큰 권한 문제일 가능성이 큽니다.
• command not found면 러너 환경이나 설치 step 순서가 잘못된 경우가 많습니다.

즉, 문제의 종류를 처음 분류하는 로그가 이 step 로그입니다.

2) 해당 job의 앞부분 로그(checkout / setup / env 주입 구간) 실패 step만 보고 끝내면 원인을 놓치는 경우가 많습니다. 그 step이 속한 job의 초반 로그를 바로 이어서 보세요. 특히 이 구간입니다.

• actions/checkout
• actions/setup-node, setup-python, setup-java 같은 런타임 설정
• 캐시 복원
• .env 생성 또는 secret 주입 관련 step

여기서 확인할 포인트는:

• 브랜치/커밋이 내가 의도한 코드인지
• Node 버전, 패키지 매니저 버전이 맞는지
• 필요한 secret이 비어 있거나 마스킹만 되고 실제로는 누락되지 않았는지
• 이전 step에서 만든 파일이 다음 step에서 정말 존재하는지

배포 실패는 겉으로는 마지막 step에서 터져도, 실제 원인은 초반 환경 설정 불일치인 경우가 많습니다.

3) 배포 대상 서비스 쪽 로그 세 번째는 GitHub Actions 바깥의 실제 배포 플랫폼 로그입니다. 예를 들면:

• Vercel 배포 로그
• Netlify deploy log
• Docker registry push 로그
• AWS/GCP/Cloudflare 쪽 배포 이벤트 로그
• 서버에 SSH 배포했다면 원격 서버의 systemd / pm2 / nginx / 애플리케이션 로그

이 로그를 꼭 봐야 하는 이유는 GitHub Actions에는 배포 요청은 보냈다까지만 찍히고, 실제 실패 원인은 외부 플랫폼에만 남는 경우가 많기 때문입니다.

예를 들어:

• GitHub Actions는 성공처럼 보였는데 Vercel에서 환경변수 누락으로 실패
• Docker 이미지는 올라갔는데 서버에서 컨테이너 시작 실패
• SSH 접속은 됐는데 대상 서버 디스크 부족으로 배포 실패

이건 Actions 로그만 보면 정확히 안 보입니다.

가장 빠른 확인 순서 시간 없을 때는 이 순서로 보면 됩니다.

1. 실패한 step 로그에서 에러 문구 한 줄을 잡습니다.
2. 바로 위로 올라가 job 초반 설정 로그를 확인합니다.
3. 그다음 배포 플랫폼 로그에서 실제 반영 단계가 어디서 깨졌는지 봅니다.

이렇게 보면 대부분의 배포 실패는 꽤 빨리 좁혀집니다.

주의할 점 - Error: Process completed with exit code 1 같은 마지막 한 줄만 보고 판단하면 안 됩니다. 그건 요약일 뿐입니다. - secret 값은 마스킹되므로, 값이 보이지 않는다와 값이 실제로 주입됐다는 다릅니다. 관련 step의 조건문과 파일 생성 여부를 같이 봐야 합니다. - 재시도 전에 어느 단계 문제인지 분류부터 해야 같은 실패를 반복하지 않습니다.

한 줄 정리 실패한 step 로그 → job 초반 환경 설정 로그 → 실제 배포 플랫폼 로그 이 3개를 먼저 보면, 배포 실패 원인을 가장 빠르게 좁힐 수 있습니다.