GitHub Actions 실패 로그를 읽을 때 덜 헤매는 방법

GitHub Actions 워크플로우가 실패했다는 알림을 받고 로그를 열면, 무수한 텍스트 중에서 원인을 찾기가 어렵다. 로그를 효율적으로 읽는 습관을 들이면 훨씬 빨리 대응할 수 있다.

1단계: 실패한 job과 step 찾기

GitHub Actions 페이지에서 실패한 workflow를 클릭하면:

❌ job-name / step-name (failed)
✓ other-job (succeeded)

빨간 X 표시가 있는 step으로 바로 이동한다. 여기가 실패 지점이다.

2단계: Step의 마지막 로그부터 읽기

step을 펼치면 위부터 차례대로 나오는데, 마지막 10줄만 먼저 본다.

2024-01-15 10:30:45 Error: Cannot find module 'lodash'
2024-01-15 10:30:45 at Function.Module._resolveFilename
2024-01-15 10:30:45     at Object.<anonymous> (/app/index.js:5:7)
...
exit code 1

거기서 원인이 명확하면 빠르게 수정할 수 있다.

3단계: 설치(setup) 단계 확인

실패가 "Cannot find module" 같은 설정 에러면, 이전 단계를 본다.

✓ Checkout code
✓ Set up Node.js (18.0.0)
✓ Install dependencies
  npm install
  npm notice found 0 vulnerabilities
❌ Run tests
  Error: Cannot find module 'lodash'

설치 단계가 완료 표시가 나왔는데도 모듈이 없다면, 로그에서 "found 0 vulnerabilities" 같은 문구가 실제로 설치를 완료했는지 확인한다.

4단계: 환경 변수나 secret 확인

"undefined" 에러가 나면 환경 변수나 secret이 없을 수 있다.

error: Cannot read property 'email' of undefined
  at createUser (api.js:42:5)

workflow 파일에서 확인한다:

- name: Deploy
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
    API_KEY: ${{ secrets.API_KEY }}
  run: npm run deploy

GitHub 저장소 Settings > Secrets and variables > Actions에서 실제로 설정돼 있는지 본다.

5단계: 시간 초과 문제

The operation timed out after 3600 seconds

Job이 너무 오래 걸리는 경우다.

jobs:
  slow-job:
    runs-on: ubuntu-latest
    timeout-minutes: 60  # 기본값은 360분(6시간)
    steps:
      - run: npm run test

6단계: 더 자세한 정보 얻기

UI에서 충분한 정보를 못 얻었다면, workflow 파일에서 디버그 로깅을 켜본다.

- name: Run tests
  run: npm run test
  env:
    DEBUG: '*'  # 많은 라이브러리가 이걸 인식

또는 더 직접적으로:

- name: Debug
  if: failure()  # 실패했을 때만 실행
  run: |
    echo "Job status: ${{ job.status }}"
    echo "Current directory: $(pwd)"
    echo "Node version: $(node --version)"
    npm ls  # 설치된 패키지 확인

7단계: 로컬에서 재현하기

CI에서만 실패하면 환경 차이를 의심한다.

# 로컬에서 workflow와 같은 환경 만들기
docker run --rm -it ubuntu:latest bash
# 또는
nvm install 18.0.0
nvm use 18.0.0

# workflow의 모든 step을 순서대로 실행
git checkout main
npm ci
npm run lint
npm run test
npm run build

8단계: 실패 로그를 커밋 메시지에 남기기

다음에 같은 문제를 만날 때 참고할 수 있도록:

fix: add missing DATABASE_URL to GitHub secrets

Previously, deploy job failed with:
  Error: Cannot read property 'email' of undefined
  at createUser (api.js:42:5)

Root cause: DATABASE_URL secret was not configured.
Fix: Added DATABASE_URL to repository secrets.

Related CI run: https://github.com/user/repo/actions/runs/12345678

자주 나오는 에러와 원인

에러	원인	해결방법
Cannot find module	의존성 설치 실패	npm ci 대신 npm install 쓰기, 패키지 락 파일 확인
undefined	환경 변수/secret 없음	GitHub Settings에서 secret 추가
Connection refused	서비스 미실행	docker-compose 또는 서비스 시작 단계 추가
Permission denied	파일 권한 문제	chmod +x script.sh
Timeout	너무 오래 걸림	timeout-minutes 증가 또는 병렬 처리

팁

# 최근 실패한 workflow 링크 빠르게 보기
gh run list --limit 5 --status failure

# 특정 workflow의 로그 다운로드
gh run view <run-id> --log

GitHub Actions 로그는 처음엔 복잡해 보이지만, 마지막 에러부터 위로 거슬러 올라가며 읽으면 빠르게 원인을 찾을 수 있다.