메인 콘텐츠로 건너뛰기
TILNOTE

Claude Code GitHub Actions 기능과 사용법 카드 정리

T
tilnote
•조회수 189
요약

Claude Code GitHub Actions란?

GitHub의 코드 관리와 PR(풀 리퀘스트) 작업을 AI가 자동으로 도와주는 툴입니다. PR 생성, 코드 구현, 버그 수정 등 다양한 작업을 직접 명령어 하나로 처리할 수 있어 개발자가 반복적인 작업에서 벗어날 수 있습니다.

주요 특징 및 장점

  • AI가 즉각적으로 PR을 만들어주고, 이슈를 코드로 구현하며, 버그도 자동으로 찾아 고쳐줍니다.

  • 개발 표준(CLAUDE.md 등)을 준수해 팀 규칙과 코드 스타일을 따라 작업합니다.

  • 설치와 설정이 매우 간단하며, API 키만 준비하면 바로 사용 가능합니다.

  • 코드가 GitHub 러너 내에서 실행되어 기본적으로 안전합니다.

지원하는 작업 예시

  • 이슈 코멘트에서 "@claude implement this feature"처럼 명령하면 AI가 코드를 만들고 PR까지 생성

  • PR 코멘트로 구현 방법이나 코드 리뷰를 요청 가능

  • 버그 고치기 등 여러 반복 작업을 자동화

설치 방법

  • 터미널 명령어 /install-github-app 또는 공식 GitHub 앱 설치로 손쉽게 시작 가능

  • 필요하다면 직접 앱/워크플로를 만들고 API 키와 환경 변수, 비밀값을 저장해서 수동 설정 가능

CLAUDE.md 파일로 표준화

프로젝트 루트에 CLAUDE.md 파일을 두면, 여기에 적힌 코드 스타일, 리뷰 기준, 프로젝트 규칙을 Claude가 인식합니다. 실무 규칙을 AI에게 정확하게 전달하는 중요한 방법입니다.

보안 설정 및 주의사항

  • API 키는 절대 코드에 직접 삽입하지 말고, GitHub "Secrets" 기능을 활용해서 보호하세요

  • 액션 권한과 워크플로우 트리거 등 불필요한 권한은 최소화하는 것이 좋습니다

  • Claude가 제안한 코드나 PR은 항상 사람이 검토 후 병합하는 게 안전합니다

비용과 리소스 관리

  • GitHub Actions는 실행 시간에 따라 별도 요금이 발생할 수 있습니다(조직 GitHub 플랜 참고)

  • Claude API 사용량(토큰 등)은 작업 복잡도, 코드 길이에 따라 다르며 별도 청구됩니다

  • @claude 명령어를 구체적으로 써서 불필요한 API 호출 최소화, 워크플로우의 반복 횟수 및 실행 시간 제한 등으로 비용을 효율적으로 관리할 수 있습니다

다양한 셋업 지원(AWS, Google Cloud)

  • AWS Bedrock, Google Vertex AI를 활용해서 엔터프라이즈 환경에서도 작동 가능하며, 데이터 위치와 보안 정책을 조직 기준에 맞추어 세팅할 수 있습니다

  • 각 클라우드별 Workload Identity, OIDC, 권한 관리 등 다양한 인증 및 환경 변수 설정 필요

예시 워크플로우 설정 코드

  • 아래와 같이 GitHub Actions 워크플로우 파일에 Claude 액션을 연결해서 사용할 수 있습니다.

# 예시: AWS Bedrock 환경에서 Claude PR 자동화
name: Claude PR Action

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

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

jobs:
  claude-pr:
    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 == 'issues' && contains(github.event.issue.body, '@claude'))
    runs-on: ubuntu-latest
    env:
      AWS_REGION: us-west-2
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-west-2
      - uses: ./.github/actions/claude-pr-action
        with:
          trigger_phrase: "@claude"
          timeout_minutes: "60"
          github_token: ${{ steps.app-token.outputs.token }}
          use_bedrock: "true"
          model: "us.anthropic.claude-3-7-sonnet-20250219-v1:0"

문제 해결 및 고급 설정

  • Claude가 명령에 반응하지 않으면 앱 설치, 워크플로우 활성화, API 키 및 권한 확인부터 점검해야 합니다

  • 인증 오류 시 각 클라우드/키 설정 및 시크릿 값 일치 여부를 확인하세요

  • Claude의 동작을 세밀히 조정하려면, 워크플로우 파일의 파라미터(prompt, timeout 등)와 CLAUDE.md/CUSTOM PROMPT를 적극 활용하세요

Claude 행동 커스터마이즈

  • CLAUDE.md로 프로젝트 기초 규칙을 지정

  • 워크플로우의 prompt 파라미터로 특정 상황/작업에 맞는 실행 지침을 전달 가능

  • 다양한 팀/프로젝트에 맞춤화된 AI 자동화 가능

각 카드들을 참고하여 Claude Code GitHub Actions를 안전하게, 효율적으로, 그리고 당신의 개발 환경 맞춤으로 활용해보세요!

출처 : Claude Code GitHub Actions - Anthropic

#GitHub 액션#AI 코드자동화#PR 관리#보안 설정#CLAUDE.md