01. GitHub Actions에서 Claude Code 활용 — 합격하는 Claude Certified Architect 자격증

GitHub Actions에서 Claude Code 활용

Claude Code를 CI에 끼워 넣는 표준 경로는 공식 액션 anthropics/claude-code-action@v1이다. 이 액션은 GitHub Actions 러너 위에서 Claude Code를 실행하므로, 에이전트의 실행 환경 자체가 사용자 인프라(GitHub 러너)이고 Anthropic 인프라가 아니다. 시험에서 "Claude Code 액션은 어디에서 코드를 실행하는가"를 물으면 답은 항상 "GitHub Actions 러너 위, 즉 사용자 쪽"이다. 이 구분은 뒤에서 다룰 권한·시크릿 설계의 출발점이 된다.

가장 빠른 설정 경로: install-github-app

가장 헷갈리지 않는 설정 방법은 액션 YAML을 손으로 쓰기 전에 터미널에서 Claude Code를 열고 /install-github-app을 실행하는 것이다. 이 명령은 GitHub App(github.com/apps/claude)을 저장소에 설치하고, 필요한 시크릿과 기본 워크플로우 파일을 함께 만들어 준다. 수동 설정도 가능하다. GitHub App을 설치하고, 인증 시크릿(ANTHROPIC_API_KEY 또는 CLAUDE_CODE_OAUTH_TOKEN)을 저장소 시크릿에 추가한 뒤, .github/workflows/ 아래에 워크플로우를 둔다. 시험에서 "사람이 가장 적게 실수하는 설정 경로"를 묻는다면 정답은 수동 YAML 작성이 아니라 /install-github-app이다.

tag 모드와 agent 모드: 트리거가 곧 모드를 결정한다

이 액션은 워크플로우 구성에 따라 두 가지 실행 모드를 자동으로 선택한다. 이 둘의 구분이 01절에서 가장 자주 출제되는 지점이다.

tag 모드는 사람이 이슈나 PR 댓글에 @claude를 멘션했을 때 대화형으로 반응하는 모드다. 트리거는 보통 issue_comment, pull_request_review_comment 같은 이벤트이고, prompt를 지정하지 않는다. @claude는 단어 경계로 인식되므로 @claude-bot이나 claude@처럼 변형하면 동작하지 않는다. 다른 트리거 문구를 쓰려면 trigger_phrase를 직접 설정해야 한다.

agent 모드는 사람의 멘션 없이 자동으로 도는 모드다. with에 prompt를 제공하면 액션이 자동으로 agent 모드로 실행된다. PR이 열릴 때마다 리뷰하거나, 예약 일정에 의존성을 점검하는 자동화가 여기에 해당한다.

# .github/workflows/claude-auto-review.ymlname: Claude Auto Reviewon:  pull_request:    types: [opened, synchronize]jobs:  review:    runs-on: ubuntu-latest    permissions:      contents: read      pull-requests: write      id-token: write    steps:      - uses: actions/checkout@v6        with:          fetch-depth: 1      - uses: anthropics/claude-code-action@v1        with:          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}          prompt: |            REPO: ${{ github.repository }}            PR NUMBER: ${{ github.event.pull_request.number }}            이 PR을 코드 품질, 잠재 버그, 보안, 성능 관점에서 리뷰하라.            상위 의견은 gh pr comment로, 특정 라인 지적은 인라인 코멘트로 남겨라.          claude_args: |            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*)"

핵심 함정 하나. prompt가 있으면 @claude 멘션이 없어도 자동으로 돈다. 시험에서 "이 워크플로우는 멘션을 기다리는가"를 묻는다면 prompt 유무로 판단한다. 멘션 기반 대화형이면 tag 모드, prompt가 있으면 agent 모드다.

인증 방식 선택: 함정이 모여 있는 곳

인증은 시험이 의사결정을 묻기 좋은 주제다. 네 갈래를 구분해야 한다.

첫째, anthropic_api_key에 ANTHROPIC_API_KEY 시크릿을 넣는 직접 API 키 방식. 가장 단순하다. 둘째, claude_code_oauth_token에 CLAUDE_CODE_OAUTH_TOKEN을 넣는 OAuth 토큰 방식. 셋째와 넷째는 클라우드 공급자 경유로, AWS Bedrock은 use_bedrock: "true", Google Vertex AI는 use_vertex: "true"를 설정하고 OIDC로 클라우드에 인증한다. 클라우드 경유 방식은 모델 ID가 공급자 접두어를 갖는다는 점을 기억해야 한다. 예를 들어 Bedrock에서는 anthropic. 접두어가 붙은 모델 ID(가령 anthropic.claude-opus-4-8)를 쓰고, 1차 API에서 쓰는 맨 모델 ID(claude-opus-4-8)를 그대로 넣으면 안 된다. 공급자별 정확한 모델 ID 문자열은 해당 공급자 문서에서 확인한다.

아래는 Bedrock + OIDC 인증의 핵심 단계를 보여주는 워크플로우다.

# .github/workflows/claude-bedrock-review.ymlname: Claude Bedrock Reviewon:  pull_request:    types: [opened, synchronize]jobs:  review:    runs-on: ubuntu-latest    permissions:      contents: read      pull-requests: write      id-token: write    steps:      - uses: actions/checkout@v6        with:          fetch-depth: 1      - 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: anthropics/claude-code-action@v1        with:          use_bedrock: "true"          prompt: |            REPO: ${{ github.repository }}            PR NUMBER: ${{ github.event.pull_request.number }}            이 PR을 검토하고 인라인 코멘트로 피드백을 남겨라.          claude_args: |            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*)"

여기서 OIDC 방식은 permissions에 id-token: write가 반드시 있어야 한다. 이 줄이 빠지면 OIDC 토큰 발급이 실패한다. 시험에서 "OIDC 인증이 실패한다, 무엇이 누락됐나"를 물으면 id-token: write를 먼저 의심한다.

권한 최소화: allowedTools와 permissions는 다른 층이다

CI에서 도는 에이전트는 사람이 즉시 승인할 수 없으므로 권한을 사전에 좁혀야 한다. 좁히는 층이 두 개라는 점을 헷갈리면 안 된다.

claude_args의 --allowedTools는 Claude Code가 쓸 수 있는 도구 자체를 화이트리스트로 제한한다. 위 예시에서 에이전트는 인라인 코멘트 생성과 gh pr comment, gh pr diff만 쓸 수 있고 임의의 셸 명령은 막힌다. 한편 워크플로우 상단의 permissions는 GitHub 토큰이 저장소에 대해 가질 수 있는 권한(읽기/쓰기)을 제한한다. CI가 PR에 코멘트를 달려면 pull-requests: write가 필요하고, 실패한 워크플로우 로그를 읽으려면 actions: read가 필요하다.

이 둘은 독립적이다. permissions로 토큰에 쓰기 권한을 줬더라도 --allowedTools에서 해당 도구를 허용하지 않으면 에이전트는 그 작업을 하지 못한다. 반대로 도구를 허용했어도 토큰 권한이 없으면 GitHub API 호출이 거부된다. 시험은 "에이전트가 코멘트를 못 단다, 어디를 고쳐야 하나"를 양쪽 모두를 후보로 두고 묻는다. 정답은 "둘 다 충족돼야 한다"이며, 보안 설계의 정답은 "두 층 모두에서 최소 권한"이다.

정리

CI 통합 표준은 anthropics/claude-code-action@v1이며, 코드 실행은 Anthropic이 아니라 GitHub 러너(사용자 인프라) 위에서 일어난다. 설정은 /install-github-app이 가장 안전한 경로다.
트리거가 모드를 정한다. @claude 멘션 기반이면 tag 모드, prompt를 제공하면 agent 모드(멘션 없이 자동 실행)다.
인증은 API 키 · OAuth 토큰 · Bedrock/Vertex OIDC 네 갈래이며, OIDC는 id-token: write가 필수, 클라우드 경유 시 모델 ID에 공급자 접두어가 붙는다.
권한은 두 층이다. --allowedTools(에이전트가 쓸 도구)와 워크플로우 permissions(토큰 권한)는 독립적이며 둘 다 최소 권한으로 충족돼야 한다.