GitHub Actions로 배포 자동화할 때 처음 막히는 곳

GitHub Actions로 배포를 자동화하려고 처음 YAML을 쓰면 로컬에서 되던 게 CI에서 안 되는 상황을 자주 만난다. 대부분은 환경 차이, secrets 이름 오타, 트리거 조건 착각이다.

실패한 워크플로 로그 보는 법

Actions 탭에서 실패한 run을 클릭하면 어느 step에서 멈췄는지 보인다. CLI로 보려면:

gh run view --log-failed

실패 step의 로그를 통째로 읽어야 한다. 흔한 실수는 에러 메시지를 제대로 읽지 않고 설정만 바꾸는 것이다. 에러 메시지가 파일을 찾을 수 없다고 하면 경로나 이름부터 확인한다.

Secrets 설정과 이름 확인

Repository Settings > Secrets and variables > Actions에서 secret을 등록한다. YAML에서는 ${{ secrets.DEPLOY_KEY }} 형태로 참조한다.

secret 이름은 대소문자를 구분한다. YAML의 secrets.deploy_key와 Settings에 DEPLOY_KEY로 등록된 건 다른 것이다. 값이 없으면 빈 문자열로 들어오고 에러 메시지도 모호하게 나오니 이름 일치 여부를 먼저 확인한다.

브랜치와 트리거 조건

on:
  push:
    branches: [main]

main에 push할 때만 트리거되도록 제한하는 게 기본이다. pull_request 이벤트도 같이 등록하면 PR에서도 배포 step까지 실행될 수 있다. 배포는 push에만 걸거나 if: github.ref == refs/heads/main 조건을 달아야 한다.

배포 후 응답 확인

배포 step 뒤에 health check step을 넣어두면 배포가 실제로 됐는지 알 수 있다.

- name: Health check
  run: |
    sleep 10
    curl -sf https://example.com/health || exit 1

로컬과 CI 환경 차이

CI runner는 완전히 새로운 환경이다. 로컬에 전역으로 설치된 CLI나 특정 버전의 Node.js가 없다. actions/setup-node로 런타임 버전을 명시하고, 필요한 도구는 워크플로에서 직접 설치해야 한다.