Claude Code CI/CD 설정: GitHub Actions를 안전하게 자동화하기

Claude Code에게 “CI/CD 만들어줘”라고 말하면 YAML은 금방 나옵니다. 하지만 실제 운영에서 중요한 것은 그 YAML이 안전한가입니다. 좋은 pipeline은 Pull Request 단계에서 깨진 코드를 막고, fork PR에는 Secrets를 넘기지 않으며, production 배포에는 사람의 승인을 남기고, 실패했을 때 rollback 경로를 갖고 있어야 합니다.

이 글에서는 Claude Code를 단순 YAML 생성기가 아니라 CI/CD 설계 파트너로 사용합니다. CI는 continuous integration, 즉 변경마다 lint, type check, test, build를 실행하는 흐름입니다. CD는 continuous delivery 또는 deployment로, 검증된 변경을 staging이나 production으로 보내는 흐름입니다. gate는 다음 단계로 가기 전에 통과해야 하는 조건입니다. Secrets는 API key나 deploy token 같은 민감 값이고, OIDC는 장기 cloud key 대신 짧은 수명의 identity token으로 접근하는 방식입니다.

적용 전에는 공식 문서를 같이 확인하세요. Claude Code Action은 Claude Code GitHub Actions, GitHub Actions 문법은 workflow syntax, token 권한은 GITHUB_TOKEN permissions, Secrets는 GitHub Secrets, production approval은 GitHub Environments를 기준으로 삼습니다. 아래 예시는 2026년 6월 3일 기준 GitHub-hosted runner에서 actions/checkout@v6, actions/setup-node@v6를 사용합니다. self-hosted runner라면 runner 버전부터 확인하세요.

자동화 경계부터 정하기

YAML을 쓰기 전에 Claude Code가 해도 되는 일과 사람이 결정해야 하는 일을 분리해야 합니다. Claude Code는 repository를 읽고 workflow를 제안하고 실패 로그를 요약하고 수정 방향을 낼 수 있습니다. 하지만 production release policy, token 권한 확대, secret scope, rollback 실행 판단은 사람이 책임져야 합니다.

영역	Claude Code에 맡기기 좋은 일	사람이 결정할 일
PR check	lint, test, typecheck, build workflow 작성	required check와 merge rule
PR review	risky diff, missing test, permission 문제 지적	수정 수용 여부
deploy	staging/production workflow 초안	approval policy와 secret scope
recovery	로그 요약, 원인 후보, rollback 절차 제안	production rollback 실행

먼저 이런 prompt로 경계를 고정합니다.

Design CI/CD for this repository.
The goals are pull request quality gates, staging deployment, Claude Code review, and production rollback.

Constraints:
- Use least-privilege GITHUB_TOKEN permissions per job.
- Do not use secrets on forked pull requests.
- If pull_request_target is suggested, explain why PR head code is not checked out.
- Put production deployment behind a GitHub Environment approval.
- Never print ANTHROPIC_API_KEY, DEPLOY_TOKEN, or other secret values.
- Produce workflow YAML that can be placed under .github/workflows/.

End with failure cases, verification commands, and rollback steps.

이 prompt는 agent에게 harness, 즉 안전한 작업 틀을 줍니다. 팀에서 반복 사용할 규칙은 CLAUDE.md에 넣어두세요. 작성 방식은 CLAUDE.md best practices가 도움이 됩니다.

Use Case 1: Pull Request 품질 게이트

첫 workflow는 PR을 merge하기 전에 깨진 변경을 막는 용도입니다. 아래 예시는 lint, typecheck, test, build를 실행하고 Node.js 22와 24 matrix로 runtime 차이를 확인합니다.

# .github/workflows/ci.yml
name: ci

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: test-node-${{ matrix.node-version }}
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        node-version: [22, 24]
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm

      - run: npm ci
      - run: npm run lint --if-present
      - run: npm run typecheck --if-present
      - run: npm test -- --runInBand

  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: test
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run build

일반적인 Node.js 프로젝트에서 npm test와 npm run build가 있으면 바로 실행할 수 있습니다. lint와 typecheck에는 --if-present를 붙였지만, 이것은 초기 도입용입니다. 안정화 후에는 Claude Code에게 package.json을 읽게 하고 실제 script만 gate로 남기세요. 테스트 전략은 Claude Code testing strategies와 같이 보면 좋습니다.

Use Case 2: Claude Code PR review를 읽기 전용으로 시작

Claude Code Action은 PR diff를 보고 GitHub Actions 권한, Secrets 노출, 테스트 부족, 관련 없는 파일 변경을 지적할 수 있습니다. 처음에는 자동 수정이 아니라 comment만 남기는 방식이 안전합니다.

# .github/workflows/claude-pr-review.yml
name: claude-pr-review

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: write
  issues: write

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    if: >
      github.event.pull_request.draft == false &&
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          prompt: |
            Review this pull request as a CI/CD safety reviewer.
            Focus on GitHub Actions permissions, secrets exposure, test coverage,
            deployment gates, rollback risk, and unrelated file changes.
            Do not edit files. Leave concise review comments with evidence.
          claude_args: |
            --max-turns 4

github.event.pull_request.head.repo.full_name == github.repository 조건은 secret을 쓰는 workflow가 외부 fork에서 돌지 않도록 막습니다. 외부 contributor PR도 검사해야 한다면 Secrets가 없는 static check와 사람이 승인한 뒤 실행하는 privileged workflow를 분리하세요. pull_request_target은 base repository 권한으로 실행되므로 특히 조심해야 합니다. Claude Code가 제안하면 왜 필요한지, 어떤 code를 checkout하는지, Secrets가 보이는지 설명하게 하세요.

보안 기준은 Claude Code security best practices와 Claude Code Git workflow를 같이 보면서 정리하는 것이 좋습니다.

Use Case 3: staging과 production 배포 gate

현실적인 CD 시작점은 main push가 staging까지 자동 배포되고, production은 manual trigger와 GitHub Environment approval을 통과하는 구조입니다. production token은 repository secret보다 production Environment secret에 두는 편이 안전합니다.

# .github/workflows/deploy.yml
name: deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  deployments: write

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build

  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: staging
    env:
      APP_ENV: staging
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run deploy:staging

  deploy-production:
    if: github.event_name == 'workflow_dispatch'
    needs: deploy-staging
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: production
    env:
      APP_ENV: production
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run deploy:production

push에서는 staging까지만 갑니다. production은 workflow_dispatch일 때만 실행되고, Environment reviewer를 걸면 사람이 최종 승인합니다. 작은 SaaS나 사내 도구에서도 이 구조는 “merge 순간 production 사고”를 크게 줄여줍니다.

Use Case 4: rollback을 먼저 준비

CI/CD에는 실패 경로가 필요합니다. production 장애가 난 뒤 rollback workflow를 만들면 늦습니다. 아래 예시는 배포할 commit SHA를 직접 입력하고 production Environment 승인을 거쳐 재배포합니다.

# .github/workflows/rollback-production.yml
name: rollback-production

on:
  workflow_dispatch:
    inputs:
      target_sha:
        description: "Commit SHA to redeploy to production"
        required: true
        type: string

permissions:
  contents: read
  deployments: write

jobs:
  rollback:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment: production
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.target_sha }}

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run build
      - run: npm run deploy:production

Claude Code에게 deploy.yml과 rollback workflow를 함께 읽히고, 오래된 commit이 build되는지, DB migration이 되돌릴 수 있는지, staging과 production 환경 변수가 다른지, 현재 배포 SHA를 추적할 수 있는지 review하게 하세요. 실패 로그 대응은 build error triage loop와 잘 이어집니다.

흔한 실패

첫째, permissions: write-all입니다. 빨리 통과시키는 대신 사고 범위를 키웁니다. contents: read에서 시작해 필요한 권한만 추가하세요.

둘째, Secrets를 로그에 찍는 것입니다. echo $DEPLOY_TOKEN 같은 확인은 하지 않습니다. 존재 확인은 값이 아니라 이름과 scope로만 합니다.

셋째, 가짜 gate입니다. --if-present는 migration 첫날에는 편하지만, 영구적으로 두면 없는 test를 통과한 것처럼 보이게 합니다.

넷째, 실패 로그 전체를 Claude Code에 던지는 것입니다. 첫 실패 command, 첫 핵심 error line, 기대 동작, local 재현 command를 주는 편이 훨씬 낫습니다.

수익화와 다음 단계

CI/CD 주제는 ClaudeCodeLab monetization과 잘 맞습니다. 독자는 단순히 궁금한 것이 아니라 production risk를 줄이고 싶어합니다. 개인 개발자는 ClaudeCodeLab products에서 CLAUDE.md, review prompt, CI checklist를 가져와 시작할 수 있습니다. 팀이 branch protection, GitHub Actions, Secrets, approval, rollback, Claude Code review를 실제 repository에 맞추고 싶다면 training and consultation이 현실적인 다음 단계입니다.

함께 읽을 글은 Advanced GitHub Actions with Claude Code, testing strategies, security best practices입니다. 실제로는 production deploy 자동화보다 PR quality gate와 read-only Claude Code review를 먼저 넣는 편이 더 빨리 효과가 납니다. 실패가 보이고, review comment가 evidence와 연결되면 merge 전 대화가 훨씬 구체적이 됩니다.