[GitHub 100일 챌린지] Day 90 - Actions 디버깅과 트러블슈팅

100일 챌린지 Day 90 - Actions 실행 중 문제를 진단하고 해결하는 방법을 배웁니다.

배울 내용

1. 디버그 로깅 활성화
2. 일반적인 오류 해결
3. 트러블슈팅 전략

---

디버그 로깅

활성화 방법

저장소 Secrets에 추가:

Settings → Secrets → Actions

Name: ACTIONS_STEP_DEBUG
Value: true

효과:

Before:
✅ Run tests
  (간단한 출력만)

After:
✅ Run tests
  ##[debug] Starting runner...
  ##[debug] Setting up environment...
  (상세한 디버그 정보)

Runner 디버그 로깅

Name: ACTIONS_RUNNER_DEBUG
Value: true

상세 Runner 내부 정보 표시

---

Workflow에서 디버깅

Debug 메시지 출력

steps:
  - name: 디버그 정보
    run: |
      echo "::debug::디버그 메시지"
      echo "::notice::알림 메시지"
      echo "::warning::경고 메시지"
      echo "::error::에러 메시지"

변수 출력

steps:
  - name: 컨텍스트 출력
    run: |
      echo "GitHub 컨텍스트:"
      echo "${{ toJSON(github) }}"
      
      echo "환경 변수:"
      env

조건부 디버깅

steps:
  - name: 테스트
    run: npm test
  
  - name: 실패 시 디버그
    if: failure()
    run: |
      echo "테스트 실패!"
      cat npm-debug.log
      ls -la

---

일반적인 오류

1. Workflow 문법 오류

증상:

Invalid workflow file

원인:

# ❌ 잘못된 들여쓰기
jobs:
build:
  runs-on: ubuntu-latest

# ✅ 올바른 들여쓰기
jobs:
  build:
    runs-on: ubuntu-latest

해결:

• YAML 문법 검증기 사용
• 들여쓰기 확인 (스페이스 2칸)
• VS Code YAML 확장 설치

2. Permission 오류

증상:

Error: Resource not accessible by integration

원인:

# GITHUB_TOKEN 권한 부족

해결:

permissions:
  contents: write  # 저장소 쓰기
  pull-requests: write  # PR 쓰기
  issues: write  # Issue 쓰기

3. Secrets 접근 오류

증상:

Secret API_KEY not found

원인:

• Secret 이름 오타
• Secret이 설정되지 않음
• Fork에서 실행 (Secrets 접근 불가)

해결:

steps:
  - name: Secret 확인
    run: |
      if [ -z "${{ secrets.API_KEY }}" ]; then
        echo "::error::API_KEY secret이 없습니다"
        exit 1
      fi

4. 캐시 문제

증상:

의존성이 최신인데도 오래된 버전 사용

해결:

# 캐시 키에 날짜 포함
- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}-${{ github.run_number }}

또는 캐시 삭제:

Actions → Caches → 삭제

---

실시간 디버깅

tmate로 SSH 접속

steps:
  - uses: actions/checkout@v4
  
  - name: 테스트
    run: npm test
  
  # 실패 시 SSH 세션 시작
  - if: failure()
    uses: mxschmitt/action-tmate@v3
    timeout-minutes: 30

사용법:

1. Workflow 실패 시 자동 대기
2. Actions 로그에서 SSH 명령 확인
3. 로컬에서 SSH 접속
4. 직접 디버깅

---

로그 분석

로그 다운로드

Actions → Workflow 실행 → "..." → Download logs

로그 검색

중요 키워드:

Error:
Warning:
Failed
##[error]
##[warning]

Annotations

steps:
  - name: 코드 품질 검사
    run: |
      # Annotation 생성
      echo "::error file=app.js,line=10::변수가 정의되지 않음"
      echo "::warning file=test.js,line=5::Deprecated 함수 사용"

---

트러블슈팅 체크리스트

Workflow 실행 안 됨

✅ 체크 사항:
- [ ] .github/workflows/ 경로 확인
- [ ] 파일 확장자 .yml 또는 .yaml
- [ ] on 트리거 설정 확인
- [ ] 브랜치/경로 필터 확인

Step 실패

✅ 디버깅 순서:
1. 로그 전체 읽기
2. 에러 메시지 확인
3. 이전 Step 성공 확인
4. 환경 변수 확인
5. 권한 확인

느린 실행

✅ 최적화:
- [ ] 캐시 사용
- [ ] 불필요한 Step 제거
- [ ] 병렬 실행 (Matrix)
- [ ] Artifacts 크기 줄이기

---

실전 디버깅 예제

복잡한 Workflow 디버깅

name: Debug Workflow

on: push

jobs:
  debug:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      # 1. 환경 정보 출력
      - name: 환경 정보
        run: |
          echo "OS: $(uname -a)"
          echo "Node: $(node --version)"
          echo "npm: $(npm --version)"
          echo "워킹 디렉토리: $(pwd)"
          echo "파일 목록:"
          ls -la
      
      # 2. GitHub 컨텍스트 출력
      - name: GitHub 컨텍스트
        run: |
          echo "저장소: ${{ github.repository }}"
          echo "브랜치: ${{ github.ref }}"
          echo "이벤트: ${{ github.event_name }}"
          echo "Actor: ${{ github.actor }}"
      
      # 3. 환경 변수 확인
      - name: 환경 변수
        run: env | sort
      
      # 4. Secrets 확인 (값 출력 안 함!)
      - name: Secrets 존재 확인
        run: |
          [ -n "${{ secrets.API_KEY }}" ] && echo "API_KEY 존재" || echo "API_KEY 없음"
      
      # 5. 의존성 설치 디버깅
      - name: 의존성 설치
        run: |
          echo "package.json:"
          cat package.json
          
          echo "설치 시작..."
          npm ci --verbose
      
      # 6. 테스트 디버깅
      - name: 테스트
        run: npm test -- --verbose
      
      # 7. 실패 시 디버그
      - if: failure()
        name: 실패 디버그
        run: |
          echo "::group::에러 로그"
          cat npm-debug.log 2>/dev/null || echo "로그 없음"
          echo "::endgroup::"
          
          echo "::group::파일 시스템"
          find . -type f -name "*.log"
          echo "::endgroup::"
      
      # 8. SSH 디버깅 (필요 시)
      - if: failure()
        uses: mxschmitt/action-tmate@v3
        timeout-minutes: 15

---

유용한 디버깅 도구

1. act (로컬 실행)

# 설치 (macOS)
brew install act

# Workflow 로컬 실행
act push

# 특정 Job만
act -j test

2. GitHub CLI

# Workflow 실행 확인
gh run list

# 로그 보기
gh run view 12345 --log

# 재실행
gh run rerun 12345

---

정리

완료 체크:

• 디버그 로깅 활성화
• 일반 오류 해결 방법 이해
• 트러블슈팅 전략 숙지

핵심 요약:

디버깅:
- ACTIONS_STEP_DEBUG: true
- echo "::debug::메시지"
- GitHub 컨텍스트 출력
- tmate로 SSH 접속

일반 오류:
- YAML 문법
- Permission
- Secrets 접근
- 캐시 문제

트러블슈팅:
1. 로그 확인
2. 에러 메시지 검색
3. 환경 정보 출력
4. 단계별 디버깅

다음: Day 91 - 최종 프로젝트 시작 →

---

← Day 90 | 전체 커리큘럼 | Day 91 →