Github Actions with Claude Code - 이론편

코드 품질과 배포 속도, 그리고 생산성 사이에서 균형을 잡는 일은 쉽지 않습니다.

협업을 하는 환경에서는 코드 리뷰의 지연이나 스타일 가이드를 따르지 않는 문제들 때문에 코드 품질이 저하되기도 합니다. 이런 상황에서 github actions와 claude code를 함께 사용하면 CI 파이프라인의 자동화를 넘어 AI 기반으로 코드 리뷰를 하고 워크플로우 최적화도 경험해 볼 수 있습니다.

Claude를 Github Actions 파이프라인에 통합했을 때 어떤 효과가 있을 수 있는지, 그리고 실제 개선이 가능한 부분과 한계점까지 살펴보도록 하겠습니다.

---

목적                    

Claude Code 를 Github actions에 통합하는 목적은 크게 3가지로 요약할 수 있습니다.

1. 개발팀의 생산성 향상입니다. 반복적인 코드 리뷰 업무를 AI 가 대신하여 개발자는 중요한 문제에 대해서 집중할 수 있는 것이죠.

2. 코드 품질 유지입니다. 스타일 가이드 준수, 안티 패턴 검줄, 잠재 버그 요소 파악, 보안 취약점 분석 등 코드 품질을 흔들 수 있는 요소들을 빠르게 검토할 수 있어 품질 관리가 한층 수월해집니다.

3. 배포 속도의 향상입니다. PR 리뷰 과정에서 발생하는 병목을 줄이고 AI를 통한 자동화 피드백 루프를 만들어 더 빠른 서비스 배포가 가능하게 하는 것이죠.

이렇게 AI 기반 리뷰와 자동화를 활용하면 자연스럽게 팀 전체의 개발자 경험이 개선될 수 있고 코드 품질 향상을 도모할 수 있기 때문에 AI를 통한 통합 워크플로우 구성은 시도해 볼 가치가 있습니다.

---

개선 가능 사항                     

그렇다면 실제 Github Actions에 Claude Code와 같은 Gen AI를 포함시켜 워크플로우를 구성하는 경우 어떤 부분에 적용을 할 수 있고 개선이 가능할까요?

Anthropic의 Github Actions 공식 문서와 claude-code-actions의 깃허브 저장소를 참고하면 다음과 같은 활용 사례를 확인해 볼 수 있습니다.

• 자동화된 PR 코드 리뷰: PR의 변경사항을 AI 가 분석하여 문제점 및 개선 방향을 제안합니다.
• 주기적인 저장소 유지 및 관리: 스케줄을 걸어 주기적으로 저장소의 작업 사항 리포트를 발행하거나 저장소 상태를 확인할 수 있습니다.
• API 변경 사항 문서 동기화: PR이나 변경사항이 있을 때 특정 경로의 파일에 변경이 있는 경우 자동으로 문서를 업데이트합니다.
• 보안 중심의 PR 리뷰: 보안 관점에 초점을 맞춘 리뷰가 가능합니다.

이처럼 Claude Code는 개발자의 코드 작성을 도와주는 역할뿐만 아니라 CI 파이프라인에서 코드와 저장소의 상태를 전반적으로 관리할 수 있는 역할을 할 수 있습니다. 이는 워크플로우 전반을 효율적으로 만들어주는 도구의 역할을 할 수 있게 됩니다.

---

Github Actions 통합                    

Claude Code 사용을 위한 인증 토큰 생성          

Claude Code를 Github Actions에서 사용하기 위해서는 먼저 인증 토큰을 준비해야 합니다. 해당하는 인증 토큰을 Github Actions의 Secret에 등록하여 Github Actions 내부 step에서 사용합니다.

github actions secret 에 secret 을 등록

방법은 두 가지입니다.

하나는 Claude Code API Key를 발급받는 것이고, 다른 하나는 OAuth 토큰 인증을 사용하는 방법입니다.

Claude Code를 사용하는 Pro/Max 사용자는 라이선스를 유지하면서 할당량 내에서 사용할 수 있는 OAuth 토큰 인증 방식을 사용하는 것을 추천드립니다. 그 외에 라이선스가 없거나 PoC 용으로 사용하거나 테스트를 하실 분들은 Claude의 API Key를 발급받아 사용하실 수 있습니다.

여기서 중요한 점은 API Key 를 사용하는 경우 선불 충전 방식으로 credit을 미리 구매하지 않은 경우에는 API 호출이 실패할 수 있기 때문에 크레디트가 없는 경우 최소 충전 금액인 5$ 의 충전이 필요합니다.

Pro 및 Max 사용자의 경우 로컬 환경에서 `claude setup-token` 명령어를 실행하면 token을 생성할 수 있습니다. 이렇게 생성한 토큰을 Github Secrets에 추가해 두면, 이후 워크플로우에서 안전하게 활용할 수 있습니다.

 

사용 사례에 따른 워크플로우 파일 생성          

토큰 설정이 완료되었다면, 실제로 사용할 워크플로우 파일을 github 저장소에 생성해주어야 합니다.

아래는 대표적으로 사용할 수 있는 두 가지 예시에 대한 워크플로우 구성입니다.

기본 사용 사례

가장 기본적인 형태는 PR 혹은 Issue에서 `@claude`라고 멘션 하는 경우 작동하는 워크플로우입니다.

# .github/workflows/claude.yml
name: Claude Code

on:
  issues:
    types: [opened, assigned]
  issue_comment:
    types: [created]
  pull_request_review:
    types: [submitted]
  pull_request_review_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write
  issues: write
  actions: read
  id-token: write

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Run Claude Code
        id: claude
        uses: anthropics/claude-code-action@beta
        with:
          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} # OAuth token 방식
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # API Key 방식

 

여기서는 별도로 prompt 내용을 지정하지 않았기 때문에  @claude라고 멘션이 달리는 경우 on 조건의 경우에 해당하면 Claude code 가 멘션 뒤에 붙는 명령어를 수행하고 결과를 응답합니다.

 

pr review 사용 사례

name: Claude Auto Review with Tracking
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          track_progress: true # ✨ Enables tracking comments
          prompt: |
            REPO: ${{ github.repository }}
            PR NUMBER: ${{ github.event.pull_request.number }}

            Please review this pull request with a focus on:
            - Code quality and best practices
            - Potential bugs or issues
            - Security implications
            - Performance considerations

            Provide detailed feedback using inline comments for specific issues.

          claude_args: |
            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

이 워크플로우는 prompt에 구체적인 지침을 담아 사용자가 요청하는 작업을 on 명령어의 조건에 해당하는 경우 즉시 수행합니다.

이렇게 특정 조건에 트리거 되는 워크플로우의 step으로 claude code를 추가하여 워크플로우를 구성할 수 있습니다.

더욱 다양한 사용 사례에 대한 정보는 공식 Github Repository의 사용 사례를 참조하세요.

---

중요 사항: Claude Code 워크플로우 최적화                    

claude code는 AI 기반으로 작동하는 것입니다. AI는 단순히 높은 확률을 가지는 응답을 하며, 언제든지 올바르지 않은 작업을 할 수 있는 가능성이 있습니다. 워크플로우에서 최적의 결과를 보장하기 위해서는 작은 설정들도 확인해서 AI의 정확성과 효율성을 높일 수 있는 방향으로 설정이 필요합니다.

Github Context는 반드시 포함          

PR이나 이슈를 분석할 때는 필요한 콘텍스트를 명확하게 제공하는 것이 중요합니다. 예를 들어 아래와 같이 prompt에 레포지토리 이름과 pr 번호를 포함시켜야 합니다.

prompt: |
  REPO: ${{ github.repository }}
  PR NUMBER: ${{ github.event.pull_request.number }}
  [Your specific instructions]

이렇게 하면 Claude 가 현재 작업 대상을 명확하게 이해하고, 올바른 콘텍스트 내에서 분석과 피드백을 제공할 수 있습니다. 콘텍스트가 부족하거나 넘치는 경우 AI의 응답에 영향을 끼칠 수 있기 때문에 콘텍스트를 올바르게 설정하는 것은 중요합니다.

`--allowedTools` 옵션으로 도구 사용 권한 부여          

Claude Code는 단순 텍스트 분석뿐만 아니라, PR 댓글 작성, 인라인 댓글, 파일 편집, Git 작업 등 다양한 도구와 연동할 수 있습니다. 이를 위해 워크플로우에서 `--allowedTools` 옵션을 사용해 권한을 명시적으로 설정해야 합니다.

예시로는 다음과 같은 권한 설정이 있습니다.

PR 댓글 : Bash(gh pr comment:*)
인라인 댓글 : mcp__github_inline_comment__create_inline_comment
파일 작업 : Read,Write,Edit
Git 작업 : Bash(git:*)

`claude_args` 에 어떤 도구를 사용할지 명시할 수 있습니다.

claude_args: |
  --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

 

모범 사례          

Claude Code를 워크플로우에서 효율적으로 사용하기 위해서는 몇 가지 모범 사례를 따르는 것이 좋습니다.

• 롬프트를 최대한 구체적으로 작성해 AI가 수행할 작업을 상세히 지시합니다.
• 예상되는 출력 형식이나 작업 성공 조건을 명확히 정의합니다.
• 반드시 저장소 관련 콘텍스트를 프롬프트에 포함시킵니다.

이런 설정을 통해 사용자는 Claude와 조금 더 나은 방식으로 협업하고 더 나은 결과를 얻을 수 있게 됩니다.

---

지금까지 Github Actions와 Claude Code를 연동해 자동화된 PR 리뷰, 보안 점검, 워크플로우 최적화까지 가능하도록 설정하는 방법과 주의사항을 살펴보았습니다.

이를 적극적이고 올바른 방식으로 활용하면 AI 기반의 워크플로우는 앞으로 효율적이고 신뢰할 수 있는 CI를 통합할 수 있을 것으로 생각됩니다.

다음 글에서는 실제로 테스트하면서 사용한 경험을 공유하려고 합니다.