GitHub Actions Workflow 에러 해결 가이드

GitHub Actions는 강력한 CI/CD 도구이지만, 워크플로우 설정이 복잡해지면 various 에러가 발생할 수 있습니다.

Environment

$ gh --version
gh version 2.40.1 (2024-01-11)

$ cat .github/workflows/main.yml
# (workflow file shown below)

Problem: 워크플로우 실행 실패

# .github/workflows/main.yml
name: CI Pipeline

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt
      - run: pytest

실행 결과:

# GitHub Actions에서 실행 시
Run pip install -r requirements.txt
ERROR: Could not find a version that satisfies that matches python==3.11.1

또는:

Error: No such file or directory: requirements.txt

Analysis: 에러 유형 분석

# Common error types:
# 1. YAML syntax errors
# 2. Action version errors
# 3. Permission errors
# 4. Path errors
# 5. Secret not found

# Debug: Enable step debug logging
# Set secret: ACTIONS_STEP_DEBUG=true

Solution: 워크플로우 에러 해결

방법 1: YAML 문법 검증

# .github/workflows/main.yml
name: CI Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        python-version: ['3.10', '3.11', '3.12']
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      
      - name: Run tests
        run: |
          pytest --cov=src tests/

방법 2: Secret 관리

# Using secrets in workflow
steps:
  - name: Deploy
    run: |
      echo "Deploying..."
      # Access secret via environment variable
      echo ${{ secrets.API_KEY }} | head -c 10
    env:
      API_KEY: ${{ secrets.API_KEY }}
      DATABASE_URL: ${{ secrets.DATABASE_URL }}

# Check if secret exists
$ gh secret list

# Set secret
$ gh secret set API_KEY --body "your-api-key"

# Set secret for specific environment
$ gh secret set API_KEY --env production --body "your-api-key"

방법 3: Artifact 관리

steps:
  - name: Build
    run: |
      python -m build
  
  - name: Upload artifact
    uses: actions/upload-artifact@v4
    with:
      name: dist
      path: dist/
  
  - name: Download artifact
    uses: actions/download-artifact@v4
    with:
      name: dist
      path: dist/

방법 4: Conditional Steps

steps:
  - name: Checkout
    uses: actions/checkout@v4
  
  - name: Run tests
    if: github.event_name == 'pull_request'
    run: pytest
  
  - name: Deploy
    if: github.ref == 'refs/heads/main'
    run: |
      echo "Deploying to production..."
      ./deploy.sh
    env:
      DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

방법 5: Reusable Workflows

# .github/workflows/reusable-test.yml
name: Reusable Test

on:
  workflow_call:
    inputs:
      python-version:
        required: false
        type: string
        default: '3.11'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ inputs.python-version }}
      - run: pip install -r requirements.txt
      - run: pytest

# .github/workflows/main.yml
jobs:
  test:
    uses: ./.github/workflows/reusable-test.yml
    with:
      python-version: '3.11'

Troubleshooting Checklist

# 1. YAML 문법 검증
$ python -c "import yaml; yaml.safe_load(open('.github/workflows/main.yml'))"

# 2. 로컬에서 테스트
$ act -j test  # Using nektos/act

# 3. 워크플로우 이력 확인
$ gh run list
$ gh run view 

# 4. 특정 실패 로그 확인
$ gh run view  --log-failed

# 5. Secrets 확인
$ gh secret list

Lessons Learned

1. YAML 문법 주의: 들여쓰기와 문법을 정확히 지켜야 합니다. YAML은 공백에 민감합니다.

2. 버전 고정: Action 사용 시 버전을 명확히 지정하세요 (예: @v4).

3. Secrets 보안: 절대 코드에 하드코딩하지 말고, GitHub Secrets를 사용하세요.

4. Matrix 전략: 여러 환경에서 테스트해야 하면 matrix를 활용하세요.

5. Reusable Workflows: 비슷한 워크플로우가 여러 개면 reusable workflow를 만들어 코드를 재사용하세요.

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.