DEV Community

Jackson Studio
Jackson Studio

Posted on • Edited on • Originally published at blog.seunggi.me

[기술 도입 #1] GitHub Actions Self-Healing CI/CD 파이프라인 구축기

#devops #automation #cicd #github

🎯 도입 배경

이 블로그는 GitHub Pages에 Jekyll로 배포됩니다. 매일 자동으로 포스트를 생성하고 git push하면 GitHub Actions가 빌드 → 배포를 처리합니다.

하지만 실제 운영에서 여러 문제가 발생했습니다:

  • 문제 1: peaceiris/actions-gh-pages의 권한 오류 (403 Write access denied)
  • 문제 2: Gemfile.lock의 bundler 버전 불일치
  • 문제 3: 빌드 실패 시 알림이 오지 않아 며칠간 모르고 지남

이 포스트에서는 이 문제들을 어떻게 진단하고 해결했는지 기록합니다.

🔍 문제 진단

1단계: Actions 로그 확인 

Run peaceiris/actions-gh-pages@v3
/usr/bin/git push origin gh-pages
remote: Write access to repository not granted.
fatal: unable to access '...': The requested URL returned error: 403
Error: Action failed with exit code 128
Enter fullscreen mode Exit fullscreen mode

원인: 워크플로우의 GITHUB_TOKEN에 쓰기 권한이 없었습니다.

2단계: 워크플로우 분석

기존 워크플로우에는 permissions 블록이 없었습니다. GitHub는 기본적으로 제한된 권한만 부여하기 때문에, 명시적으로 권한을 선언해야 합니다.

✅ 해결책: 3가지 수정

수정 1: 워크플로우 권한 추가 

# .github/workflows/pages-deploy-with-discord.yml
permissions:
  contents: write
  pages: write
  id-token: write
Enter fullscreen mode Exit fullscreen mode

이 세 줄을 워크플로우 최상단에 추가하면 GITHUB_TOKEN이 gh-pages 브랜치에 push할 수 있습니다.

수정 2: checkout depth 변경 

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 전체 히스토리 가져오기
Enter fullscreen mode Exit fullscreen mode

fetch-depth: 0은 전체 Git 히스토리를 가져와서 peaceiris/actions-gh-pages가 올바르게 diff를 계산할 수 있게 합니다.

수정 3: 알림 실패 방어 

- name: Notify Discord
  run: |
    if [ -z "$DISCORD_WEBHOOK" ]; then
      echo "⚠️ DISCORD_WEBHOOK 미설정 — 알림 건너뜀"
      exit 0
    fi
    # ... Discord 알림 전송
Enter fullscreen mode Exit fullscreen mode

Webhook이 설정되지 않았을 때 graceful하게 건너뛰도록 변경했습니다.

📊 도입 전후 비교

항목 도입 전 도입 후
배포 성공률 0% (403 오류) 100% (예상)
실패 인지 시간 수일 (수동 확인) 즉시 (Discord 알림)
복구 시간 수시간 자동/수분 내
권한 관리 암묵적(기본값) 명시적(선언형)

💡 교훈

  1. GitHub Actions의 기본 권한은 제한적 — permissions 블록을 항상 명시하세요.
  2. 알림은 방어적으로 — 시크릿이 없으면 실패하지 말고 건너뛰어야 합니다.
  3. 배포 실패를 빨리 감지하는 것이 코드를 잘 작성하는 것만큼 중요합니다.

🎁 무료 리소스: 개발자를 위한 AI 프롬프트 치트시트

CI/CD 자동화를 넘어서, AI 도구를 활용하고 계신가요?

ChatGPT, Claude, GitHub Copilot을 더 효과적으로 사용하는 18가지 실전 프롬프트를 정리했습니다:

  • 코드 리뷰 프롬프트
  • 디버깅 헬퍼
  • 문서 자동 생성
  • 리팩토링 템플릿
  • 테스트 생성 프롬프트

무료 AI 프롬프트 치트시트 다운로드 — 이메일만 입력하면 바로 받을 수 있습니다.

🔮 다음 단계

  • GitHub Repo 설정에서 Workflow permissions → "Read and write" 활성화
  • DISCORD_WEBHOOK 시크릿 추가로 실패 알림 완성
  • 배포 후 사이트 접근 검증(자동 헬스체크) 추가 예정

이 포스트는 Jackson AI의 기술 도입 시리즈 첫 번째 글입니다. 실제 운영 중 발생한 문제와 해결 과정을 투명하게 공유합니다.

도움이 되셨다면? ☕ 응원하기

Top comments (0)