Advanced GitHub Actions with Claude Code: permissions, OIDC, cache, and matrix CI

GitHub Actions is easy when the goal is only “run tests on push.” It becomes harder when a team needs safe permissions, predictable caching, matrix coverage, cloud deployment, and AI-assisted review without leaking secrets.

This guide treats Claude Code as a workflow design partner, not a YAML vending machine. The examples are complete GitHub Actions workflows you can copy, adjust, and run. The important part is the review discipline around them: every job should explain why it needs each permission, which secrets it can see, and what happens when a pull request comes from a fork.

I checked the current guidance against GitHub Docs for workflow syntax, GITHUB_TOKEN permissions, AWS OIDC, dependency caching, and concurrency. For Claude Code itself, use the current Claude Code GitHub Actions documentation.

Architecture

Advanced CI is not about adding more automation. It is about narrowing blast radius, skipping stale work, making failures diagnosable, and keeping human approval around production changes.

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"]

Some terms matter before writing YAML. A matrix creates several jobs from a table of values, such as Node.js 22 and 24 across Ubuntu and Windows. OIDC, or OpenID Connect, lets a workflow exchange a short-lived GitHub identity token for cloud credentials, so you do not store long-lived AWS keys in GitHub Secrets. Concurrency controls whether older runs should keep executing after a newer commit arrives. Permissions define what the workflow’s GITHUB_TOKEN can do.

Use cases

Use case one is a pull request quality gate. Run lint, type checking, and tests on more than one runtime before merge. This catches Windows path issues, Node runtime differences, and lockfile drift before they reach main.

Use case two is a staging deployment. After main passes, GitHub Actions assumes an AWS role through OIDC and deploys without a static access key. Production can add a GitHub Environment approval so automation cannot publish alone.

Use case three is shared CI for a monorepo. If ten packages repeat the same setup, a reusable workflow keeps the Node version, install command, and cache policy in one place.

Use case four is Claude Code review. Start with read-only analysis and PR comments. Give Claude Code broader write permissions only after you have branch protection, required review, and rollback rules.

Prompt Claude Code with constraints

Ask Claude Code to design under constraints before asking it to write files.

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.

That prompt changes the output. Claude Code now has to explain security decisions instead of merely filling a workflow template.

PR Quality Gate

This workflow uses actions/checkout@v6 and actions/setup-node@v6, current major versions as of June 2026. GitHub-hosted runners are fine. If your organization uses self-hosted runners, update the runner before adopting these newer actions.

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

The workflow only needs contents: read, because tests do not write to the repository. concurrency cancels stale runs from older commits on the same branch. The cache is tied to package-lock.json; avoid caching node_modules unless you have a strong reason, because native modules and OS differences can make it brittle.

Deploy to AWS with OIDC

The secure pattern is to register GitHub as an OIDC provider in AWS, create a narrow IAM role, and restrict the role trust policy by repository, branch, or environment. The workflow still needs id-token: write; without it, GitHub cannot mint the OIDC token.

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"

Replace the role ARN, region, and deploy command. The structure is still real workflow syntax. For production, use a separate environment and required reviewers.

Reusable Workflow

Reusable workflows are useful when several workflows repeat the same setup. They also prevent action-version drift.

# .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

Caller 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"

Do not hide real differences inside a giant reusable workflow. If packages need different install commands, ask Claude Code to separate shared setup from package-specific steps.

Claude Code PR Review

Claude Code Action v1 uses anthropics/claude-code-action@v1, prompt, and claude_args. Do not copy old @beta examples that use removed inputs.

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

This skips forked pull requests because repository secrets are not available there. If you need fork support, design a separate low-trust path that does not expose secrets or run untrusted code with privileged permissions.

Failure Cases

The most dangerous failure is using pull_request_target and checking out the pull request head. That can run untrusted code with access closer to the base repository’s permissions. Use pull_request_target only for workflows that do not execute PR code, such as labeling or safe metadata comments.

Another common failure is printing secrets while debugging. GitHub masks many exact secret values, but derived values, JSON-wrapped tokens, base64 text, and third-party debug output can still leak. Give Claude Code secret names and purposes, not secret values.

Caching can also break builds. A broad key such as node-cache can restore stale dependencies after the lockfile changes. Tie cache keys to lockfiles and prefer setup action caching before manually caching node_modules.

Matrix builds can become expensive. Two OSes times two Node versions is reasonable. Three OSes, four runtimes, and eight packages become 96 jobs. Run the small matrix on PRs and broader coverage on nightly schedules.

Finally, watch action versions. Newer official actions now use newer Node runtimes. Self-hosted runners must be upgraded before you move everything to current major versions.

Monetization Path

Safer CI helps revenue work: landing pages, paid templates, checkout flows, lead forms, and course content can ship in smaller changes without risking broken deploys or leaked keys. For solo work, start with the free Claude Code cheat sheet. For teams that need permissions, OIDC, Claude Code review, branch protection, and monorepo CI designed against a real repository, use Claude Code training and consultation.

Related guides: CI/CD pipeline setup, Git workflow, testing strategy, and security best practices.

Hands-on Result

For this article, I extracted the fenced YAML examples from the MDX and checked them with a YAML parser. The examples parse as YAML and cover on, permissions, concurrency, matrix jobs, reusable workflows, OIDC deployment, and Claude Code Action v1. Before running them in a real repository, replace the AWS role ARN, npm scripts, environment name, and ANTHROPIC_API_KEY secret.