GitHub Actions 실패 로그를 읽는 순서

GitHub Actions가 실패하면 웹 UI에서 로그를 찾아 클릭하게 되는데, step이 많으면 실패한 곳까지 스크롤하는 게 귀찮다. gh CLI를 쓰면 터미널에서 바로 볼 수 있다.

gh run view --log-failed

실패한 step의 로그만 출력한다. 어느 줄에서 exit code가 0이 아니었는지, 어떤 에러 메시지가 나왔는지 바로 보인다.

특정 run ID를 지정하려면:

gh run view <run-id> --log-failed

실패 원인을 좁히는 순서

로그를 보면서 확인하는 순서가 있다.

1. 어느 step에서 실패했는가

gh run view --log-failed 출력 상단에 실패한 job과 step 이름이 나온다. step 이름을 먼저 확인하면 원인 범위가 좁아진다.

2. secret과 환경변수 이름 확인

secret or variable not found 또는 undefined 같은 에러가 나오면 secret 이름이 틀린 경우가 많다. 워크플로 YAML의 ${{ secrets.MY_KEY }}와 Settings > Secrets에 등록된 이름이 정확히 일치해야 한다. 대소문자까지 같아야 한다.

3. 로컬과 runner 환경 차이

로컬에서는 되는데 CI에서 실패하면 환경 차이가 원인인 경우가 많다. Node 버전, 패키지 lock 파일, 환경변수 유무를 확인한다.

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

cache: 'npm'을 쓰면 npm ci가 빨라지고, lock 파일 기반으로 캐시를 잡으므로 의존성 불일치도 줄어든다.

배포 단계 실패라면

배포 step이 실패한 경우 배포 대상 서버나 서비스의 응답을 직접 확인해야 한다.

curl -I https://example.com

Actions 로그에는 배포 명령의 exit code와 stdout만 남는다. 실제 서버 상태는 로그 밖에서 확인해야 하는 경우가 있다.

로그를 텍스트로 저장

나중에 참고하려면 로그를 파일로 저장해두는 게 편하다.

gh run view <run-id> --log-failed > /tmp/actions-fail.log

Actions 로그는 일정 기간 후 삭제되므로, 반복해서 나는 실패라면 패턴을 기록해두는 게 도움이 된다.