GitHub Actions 배포 job 이름을 읽기 쉽게 정리하기

GitHub Actions를 운영하다 보면 자동화된 workflow가 점점 복잡해진다. 배포 로그를 볼 때마다 "이 step은 뭐 하는 거지?" 헷갈리는 경험은 누구나 있다.

Job 이름부터 명확하게

workflow 파일에서 job 이름이 모호하면 로그를 읽을 때마다 YAML을 다시 봐야 한다.

# 나쁜 예
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - name: step1
        run: echo "test"

  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - name: step2
        run: npm run build

# 좋은 예
jobs:
  test:
    name: Run tests
    runs-on: ubuntu-latest
    steps: [...]

  build-and-push:
    name: Build Docker image and push to registry
    runs-on: ubuntu-latest
    needs: test
    steps: [...]

  deploy-production:
    name: Deploy to production server
    runs-on: ubuntu-latest
    needs: build-and-push
    steps: [...]

Step 이름도 동작을 명확히 하기

step마다 이름을 붙이면 로그에서 어느 단계가 실패했는지 한눈에 알 수 있다.

- name: Checkout code
  uses: actions/checkout@v4

- name: Set up Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18'

- name: Install dependencies
  run: npm ci

- name: Run linter
  run: npm run lint

- name: Run tests
  run: npm run test

- name: Build application
  run: npm run build

- name: Push Docker image to registry
  run: |
    docker build -t myapp:latest .
    docker push myapp:latest

조건부 실행은 step 이름에 명시하기

특정 조건에서만 실행되는 step이라면 이름에 반영한다.

- name: Deploy to staging (if not main branch)
  if: github.ref != 'refs/heads/main'
  run: ./deploy-staging.sh

- name: Deploy to production (main branch only)
  if: github.ref == 'refs/heads/main' && success()
  run: ./deploy-production.sh

로그 출력도 명확하게

step 안에서도 로그 메시지를 명확히 해야 나중에 빠르게 찾을 수 있다.

- name: Check deployment status
  run: |
    echo "=== Checking deployment on production ==="
    echo "URL: https://example.com"
    curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" https://example.com
    if [ $? -eq 0 ]; then
      echo "✓ Deployment successful"
    else
      echo "✗ Deployment check failed"
      exit 1
    fi

실패 시 빠르게 원인 파악하기

로그가 명확하면 GitHub Actions 실패 시 빠르게 대응할 수 있다.

- name: Upload build artifacts
  if: always()
  run: |
    echo "Build output path: ./dist"
    ls -la ./dist || echo "Build directory not found"

작은 것처럼 보이지만 job과 step의 이름을 잘 짓는 것만으로도 운영 부담이 크게 줄어든다.