Claude Code로 GitHub Actions 고도화하기: 권한, OIDC, cache, matrix CI

GitHub Actions에서 “push하면 test 실행” 정도는 금방 만들 수 있습니다. 어려운 부분은 필요한 권한만 주고, 오래된 실행을 멈추고, cache가 낡은 dependency를 재사용하지 않게 하며, cloud deploy에서 장기 access key를 없애는 일입니다.

이 글에서는 Claude Code를 단순 YAML 생성기가 아니라 workflow 설계 파트너로 사용합니다. 아래 예시는 복사해서 일부 값만 바꾸면 사용할 수 있는 GitHub Actions workflow입니다. 핵심은 각 job이 왜 그 permission을 필요로 하는지, 어떤 secret을 볼 수 있는지, fork pull request에서는 어떻게 동작하는지 설명할 수 있어야 한다는 점입니다.

공식 기준은 GitHub Docs의 workflow syntax, GITHUB_TOKEN permissions, AWS OIDC, dependency caching, concurrency, 그리고 Claude Code GitHub Actions를 확인했습니다.

전체 구조

고급 GitHub Actions는 자동화를 많이 붙이는 일이 아닙니다. 실패 원인을 찾기 쉽고, 권한 범위가 좁고, 오래된 실행이 취소되고, production 변경에는 사람이 승인할 자리가 남아 있어야 합니다.

flowchart LR
  PR["Pull request"] --> Gate["matrix test and lint"]
  Gate --> Cache["lockfile cache"]
  Gate --> Claude["Claude Code review"]
  Gate --> Deploy["OIDC deploy"]
  Deploy --> Env["GitHub environment approval"]
  Env --> AWS["AWS role"]

용어를 먼저 정리합니다. matrix는 Node.js 22와 24, Ubuntu와 Windows처럼 값의 조합으로 여러 job을 만드는 조건표입니다. OIDC는 OpenID Connect이며, GitHub Actions의 짧은 수명 identity token을 AWS 같은 cloud credential로 교환하는 방식입니다. 그래서 장기 AWS access key를 GitHub Secrets에 저장하지 않아도 됩니다. concurrency는 같은 종류의 workflow가 동시에 실행되는 것을 제어합니다. permissions는 GITHUB_TOKEN이 무엇을 할 수 있는지 정하는 목록입니다.

실제 유스케이스

첫 번째는 pull request 품질 gate입니다. lint, type-check, test를 여러 Node.js 버전과 OS에서 실행하면 Windows path 문제, Node runtime 차이, lockfile drift를 merge 전에 발견할 수 있습니다.

두 번째는 staging deploy입니다. main에 merge된 뒤 GitHub Actions가 OIDC로 AWS IAM role을 assume하고, 정적 access key 없이 배포합니다. production은 GitHub Environment approval을 추가해 자동화가 단독으로 배포하지 못하게 합니다.

세 번째는 monorepo 공통 CI입니다. 여러 package가 같은 Node setup과 install, test를 반복한다면 reusable workflow로 분리합니다. 그래야 action version이나 cache 정책이 파일마다 달라지는 일을 줄일 수 있습니다.

네 번째는 Claude Code PR review입니다. 처음부터 자동 수정 권한을 주지 말고, diff를 읽고 위험한 부분을 comment하는 역할부터 시작하는 편이 안전합니다.

Claude Code에 줄 요청

YAML부터 쓰게 하지 말고, 제약을 먼저 명시하게 합니다.

Design GitHub Actions for this repository.
The goals are pull request quality gates, staging deployment, and Claude Code review.

Constraints:
- Use least-privilege GITHUB_TOKEN permissions.
- Use OIDC for AWS. Do not store long-lived AWS access keys in Secrets.
- Include package-lock.json in dependency cache keys.
- Assume secrets are not available on forked pull requests.
- If pull_request_target is suggested, explain why PR head code is not checked out.
- Produce GitHub Actions YAML that is valid as written.

End with concrete failure cases and verification steps.

이렇게 요청하면 Claude Code가 단순 template이 아니라 보안 판단까지 설명해야 합니다.

PR 품질 gate

아래 예시는 actions/checkout@v6와 actions/setup-node@v6를 사용합니다. 2026년 6월 기준 최신 major 흐름입니다. GitHub-hosted runner는 보통 바로 사용할 수 있지만, self-hosted runner는 runner version을 먼저 확인해야 합니다.

name: pr-quality-gate

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

permissions:
  contents: read

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

jobs:
  test:
    name: node-${{ matrix.node }}-${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [22, 24]

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

      - name: Test
        run: npm test

test job은 repository에 쓰지 않으므로 contents: read면 충분합니다. concurrency는 같은 branch에 새 commit이 올라왔을 때 오래된 실행을 취소합니다. cache는 package-lock.json과 묶습니다. node_modules 전체를 cache하면 OS 차이나 native module 때문에 불안정해질 수 있습니다.

OIDC로 AWS deploy

AWS에서는 GitHub OIDC provider를 신뢰하도록 등록하고, 좁은 IAM role을 만든 뒤 trust policy에서 repository, branch, environment 조건을 제한합니다. workflow에는 id-token: write가 필요합니다. 이 권한은 OIDC token 발급을 허용할 뿐 repository write 권한이 아닙니다.

name: deploy-staging

on:
  workflow_dispatch:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

concurrency:
  group: deploy-staging
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    environment: staging

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/claude-code-github-actions-staging
          aws-region: ap-northeast-1

      - name: Verify caller identity
        run: aws sts get-caller-identity

      - name: Deploy
        run: |
          npm ci
          npm run build
          echo "Deploy command goes here"

실제 repository에서는 role ARN, region, deploy command를 바꾸면 됩니다. production은 별도 environment와 required reviewers를 사용하세요.

Reusable workflow

반복되는 Node check는 reusable workflow로 뺄 수 있습니다. 공통 함수처럼 쓰되, secret은 자동으로 전부 전달되지 않는다는 점을 기억해야 합니다.

# .github/workflows/reusable-node-check.yml
name: reusable-node-check

on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "24"

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install
        run: npm ci

      - name: Check
        run: |
          npm run lint
          npm run typecheck
          npm test

호출하는 workflow는 짧아집니다.

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

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  node-check:
    uses: ./.github/workflows/reusable-node-check.yml
    with:
      node-version: "24"

package마다 install 방식이 다른 monorepo라면 무리하게 하나로 합치지 마세요. Claude Code에는 공통 setup과 package별 step을 분리해 달라고 요청하는 편이 낫습니다.

Claude Code PR review

Claude Code Action v1은 anthropics/claude-code-action@v1, prompt, claude_args를 사용합니다. 예전 @beta나 direct_prompt 예시는 그대로 복사하지 마세요.

name: claude-pr-review

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

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

jobs:
  review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Claude Code review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request as a senior engineer.
            Focus on security, broken tests, unnecessary permissions, and missing verification.
            Do not modify files. Leave concise review comments only.
          claude_args: |
            --max-turns 5

이 workflow는 fork PR을 skip합니다. 일반적으로 fork PR에는 repository secret이 제공되지 않기 때문입니다. 외부 contributor까지 지원하려면 secret 없이 동작하는 별도 저신뢰 경로를 설계해야 합니다.

자주 나는 실패

가장 위험한 실수는 pull_request_target에서 PR head를 checkout하는 것입니다. 이 event는 base repository 권한에 가까워질 수 있으므로, 외부 fork code를 높은 권한으로 실행하면 secret 노출 위험이 생깁니다.

두 번째는 debug 목적으로 secret을 출력하는 일입니다. GitHub가 많은 secret 값을 mask하지만, 변형된 문자열, JSON 안의 token, base64 값, 외부 도구의 debug log까지 항상 안전하지는 않습니다. Claude Code에는 secret 값이 아니라 이름과 용도만 알려 주세요.

세 번째는 cache key가 너무 넓은 경우입니다. key: node-cache처럼 고정하면 lockfile 변경 후에도 낡은 dependency를 복원할 수 있습니다. cache-dependency-path나 hashFiles('**/package-lock.json')를 사용하세요.

네 번째는 matrix 폭발입니다. OS 2개와 Node 2개는 적절하지만, OS 3개, runtime 4개, package 8개면 96 job입니다. PR은 대표 조합만, nightly는 넓은 조합으로 나누는 편이 좋습니다.

다섯 번째는 action major를 방치하는 일입니다. 2026년 기준 공식 action들은 새 Node runtime으로 이동하고 있습니다. self-hosted runner를 쓰는 조직은 workflow보다 runner update를 먼저 확인해야 합니다.

수익과 팀 도입

안전한 CI는 수익과도 연결됩니다. landing page, 유료 template, checkout flow, 강의 페이지, 문의 form을 작은 PR로 자주 배포할 수 있고, secret leak이나 깨진 deploy 위험을 낮출 수 있습니다. 개인이라면 무료 Claude Code cheatsheet로 시작하세요. 팀에서 permissions, OIDC, Claude Code review, branch protection, monorepo CI를 실제 repository 기준으로 설계해야 한다면 Claude Code 교육 및 컨설팅을 활용할 수 있습니다.

관련 글로 CI/CD pipeline setup, Git workflow, testing strategy, security best practices를 함께 보세요.

직접 확인한 결과

이 글의 fenced YAML 예시는 MDX에서 추출해 YAML parser로 문법을 확인했습니다. on, permissions, concurrency, matrix, reusable workflow, OIDC deployment, Claude Code Action v1 구조가 YAML로 해석되는 것을 확인했습니다. 실제 실행 전에는 AWS role ARN, npm scripts, environment 이름, ANTHROPIC_API_KEY secret을 repository에 맞게 바꿔야 합니다.