Module 1: Claude Code in GitHub Actions

Overview

So far, in guides 1-9 of the path, you've used Claude Code on your local machine: you open it, give it a task, see the result. It's powerful, but limited to your active session. This guide closes that gap: you're going to set up Claude Code so it operates automatically on every pull request, on every push, without you having to open anything.

This module is the entry point. GitHub Actions is the most widely adopted CI/CD platform in the industry — 65% of public repositories on GitHub use it, and most professional projects do too. Setting up Claude Code as a step in a GitHub Actions workflow is the most direct way to make the leap from "local tool" to "production agent."

By the end of the 5 capsules, you'll have a YAML workflow that runs Claude Code on every pull request, with secrets handled securely, output parsed correctly, and costs controlled with basic rate limiting. It's the foundation on which the whole pipeline of the guide is built.

Where We Are in the Guide

Phase 1: Pre-Merge Automation (Modules 1-2)
├── Module 1: Claude Code in GitHub Actions ← YOU ARE HERE
│   → YAML workflow, secrets, output parsing, costs
└── Module 2: Automated Code Review on PRs
    → A bot that comments inline on PRs

Phase 2: Cross-Platform and Deployment (Modules 3-4)
├── Module 3: GitLab CI/CD and Headless SDK
└── Module 4: Deployment Automation

Phase 3: Resilience and Project (Modules 5-6)
├── Module 5: Security Scanning and Rollback
└── Module 6: Integrative Project — Complete Pipeline

This is Module 1 of 6 — the foundation. Every later module adds capabilities to the pipeline you kick off here. Without this module working, the other modules lose context.

The Mental Shift: From Local to Automatic

There's a categorical difference between "using Claude Code" and "having Claude Code working for you":

LOCAL USE (what you already know):
→ You open your terminal, launch Claude Code
→ You give it a task: "review this code"
→ You wait, see the result
→ You close the session
→ Tomorrow you repeat it for the next PR

CI/CD USE (what you learn in this guide):
→ You open a PR on GitHub
→ Claude Code analyzes the code without you doing anything
→ You see the result on the PR page
→ You move on to your next task
→ This happens on every PR, automatically, forever

The difference isn't speed — it's scalability and consistency. The first mode depends on you remembering to do it. The second depends on nothing — it just happens. And when it just happens, it happens on every PR from every team member, not only when you're available.

A Real Task: Before and After

To anchor the module, consider a typical scenario for a team of three developers:

Team task: Ensure every PR goes through Claude Code analysis before a human reviews it. The goal: catch obvious problems early so the human reviewer focuses on things that require judgment.

Approach A: Without CI/CD (what many teams do today)

Monday 10:00 → Developer opens PR
Monday 11:00 → Human reviewer notices something is off
Monday 11:15 → Reviewer asks developer to run Claude Code
              on the diff locally
Monday 14:00 → Developer finds time, does it, finds
              2 issues, fixes them
Monday 16:00 → Re-review, merge

PROBLEMS:
- Inconsistent: depends on the reviewer asking for analysis
- Late: issues are caught after the reviewer
  already invested time
- Doesn't scale: every developer has to remember to do it
- No record: the analysis doesn't live in the PR

Approach B: With GitHub Actions (what you learn here)

Monday 10:00 → Developer opens PR
Monday 10:01 → GitHub Actions triggers the workflow automatically
Monday 10:03 → Claude Code completes its analysis
Monday 10:03 → The analysis shows up as a check on the PR
              + a comment summarizing the findings
Monday 10:30 → Human reviewer sees the PR WITH the analysis already done
              and focuses on what the agent can't judge
Monday 11:00 → Merge

ADVANTAGES:
- Consistent: happens on EVERY PR, no exceptions
- Early: issues are caught before the human review
- Scales: applies to the whole team with no individual effort
- Record: the analysis lives in the PR for future auditing

Same task. Same team. Radically different result in consistency and speed.

The difference wasn't the quality of the analysis — the analysis is the same Claude Code. The difference was automating the trigger and standardizing the output. Those are the two things this module teaches.

Prerequisites

Required knowledge:

✅ Guides 1-9 of the path completed (Claude Code basics, prompt engineering, MCP, debugging, testing, refactoring, advanced workflows)
✅ Claude Code's headless SDK (Guide 9, module 6) — the technical foundation of this module
✅ Familiarity with Git and pull requests
✅ A GitHub account with a repository you can push to

NOT required:

❌ You don't need to have written a GitHub Actions workflow from scratch
❌ You don't need to know GitLab CI/CD or other platforms (that's Module 3)
❌ You don't need Docker (basic workflows don't require it)

Module Roadmap

Capsule 01 — Module introduction (this capsule)

Context for the shift from local to CI/CD. The before/after scenario.

Capsule 02 — Your first YAML workflow

Anatomy of a GitHub Actions workflow: triggers, jobs, steps. Your first YAML that runs Claude Code on every PR. Running it and seeing the result.

Capsule 03 — Secrets management with GitHub Secrets

How to handle your ANTHROPIC_API_KEY securely. Why it should never go in the YAML. Secrets at the repository, organization, and environment level. Limitations and best practices.

Capsule 04 — Parsing output and generating artifacts

Claude Code produces text — you need to turn it into something useful. PR comments, annotations, downloadable artifacts. Strategies depending on the use case.

Capsule 05 — Costs and rate limiting

Every run costs money. How to calculate the cost per PR. Strategies to run selectively: only on relevant PRs, only on modified files, only if previous tests passed. When to skip.

Progression map

Capsule 01 (this)  → Why CI/CD for Claude Code
Capsule 02         → Your first working workflow
Capsule 03         → Secure secrets management
Capsule 04         → Useful output (not ignored logs)
Capsule 05         → Costs under control

Difficulty: ⭐⭐ ──────────────────▶ ⭐⭐⭐

What You'll Achieve in This Module

By completing the 5 capsules, you'll be able to:

Create a YAML workflow that runs Claude Code on every pull request
Configure appropriate triggers (pull_request: opened, synchronize) without generating unnecessary runs
Handle secrets securely with GitHub Secrets — without leaking API keys
Parse the output of Claude Code and generate visible artifacts (comments, annotations)
Calculate and control costs — know how much each PR run costs and how to optimize it
Run the workflow end-to-end and verify it runs on real PRs

The before and after

BEFORE the module:
→ "Claude Code is a tool I open when I need it"
→ "The analysis depends on me remembering it"
→ "Every developer on the team uses it differently"

AFTER the module:
→ Claude Code runs on EVERY PR without anyone triggering it
→ The results are consistent for the whole team
→ Costs are controlled and predictable
→ The analysis lives as part of the PR, not as an ephemeral conversation

What This Module Does NOT Cover

Topic	Where it's covered
Inline comments on PRs (line-level)	Module 2
GitLab CI/CD	Module 3
Deployment automation	Module 4
Security scanning with Claude Code	Module 5
Complete end-to-end pipeline	Module 6
Vulnerabilities specific to AI code	Guide #11 (Security)

This module is the foundation: you learn how to put Claude Code in GitHub Actions technically and operationally. The specific applications (review, deployment, security) come in later modules.

Pitfalls to Avoid While Taking This Module

Five predictable misunderstandings. Anticipate them before you start.

1. "Hardcoding the API key in the YAML 'temporarily'"

No. Hardcoding secrets in YAML exposes them in the git history forever, even if you move them to Secrets later. The module's rule is absolute: API keys go in GitHub Secrets from the first commit, no exceptions. If you rotate the key afterward, the damage is already done — and rotating requires revoking the old one, which interrupts the whole team.

2. "Configuring triggers on push with no filters"

Running the workflow on every push (not just PRs) generates unnecessary costs and floods the Actions dashboard. The right thing is to configure specific triggers — pull_request: [opened, synchronize] and optionally push: [main] with path filters. Capsule 05 develops the economics of when to run and when not to.

3. "Ignoring costs because 'Claude Code is cheap'"

Every API call costs. With a team of 5 developers and 10 PRs per week, 5 updates per PR, that's 250 runs a week. At a few cents per run, that's several hundred dollars a month — not insignificant. Capsule 05 teaches you to budget and optimize.

4. "Output as a log nobody reads"

Claude Code generates text. If that text only ends up in the GitHub Actions logs, nobody reads it. Developers look at PRs, not workflow logs. Any useful finding has to land in the PR itself: as a comment, annotation, or check status. Capsule 04 develops the strategies.

5. "Treating the workflow as throwaway code"

A YAML workflow is production code: it runs on every PR, affects the whole team, and its errors are visible. It needs the same care as any code: review, versioning of actions, comments when something isn't obvious. Treating the YAML as "quick configuration I can change later" leads to fragile workflows that break for no apparent reason.

Diagnosis: What's Your Starting Point?

Five questions to calibrate before you start.

Question 1: Have you written a GitHub Actions workflow before? If so, did you write it or copy it?

If you wrote it: you have an advantage. The module formalizes what you already intuit and adds Claude Code.

If you copied it: that's fine — most people start that way. Capsule 02 walks you through the anatomy piece by piece so you stop copying and start writing.

Question 2: Do you know the difference between a secret at the repository, organization, and environment level?

If yes: capsule 03 formalizes what you already intuit and adds best practices.

If no: that's exactly what capsule 03 teaches you. The distinction matters so you don't expose secrets more than necessary.

Question 3: How much do you think it costs to run Claude Code 100 times in a month?

If you have a figure: capsule 05 helps you validate and control it.

If not: most people don't have one — and that's why the bills come as a surprise. Capsule 05 gives you the calculation and the optimization strategies.

Question 4: If Claude Code analyzes a PR and finds something important, where does that finding show up?

If you said "in the workflow logs": it works technically, but nobody reads them. Capsule 04 shows you how to land the finding in the PR itself.

If you said "as a PR comment or check": you're on the right track. Capsule 04 gives you the concrete techniques.

Question 5: What happens if your workflow fails (not Claude Code, but the YAML itself)?

If you have a plan: capsule 02 formalizes it with workflow debugging.

If not: workflows fail more often than it seems (deprecated action, YAML syntax, missing permissions). Capsule 02 teaches you to read logs and fix them.

If you hesitated on 3 or more: this module is a priority before moving on. If you answered all of them confidently, use it as a focused review on capsule 05 (costs and rate limiting), which almost nobody masters at the start.

How to Work Through This Module

Capsule 02 is the most hands-on. Read it with a GitHub repository open beside you so you can do each step.
Capsule 03 is the most important for production. Poorly handled secrets are the #1 cause of incidents in CI/CD.
Capsule 04 is where the module becomes useful. Without visible output, everything before it is pure exercise.
Capsule 05 is the one that saves your team money. Don't treat it as optional.

Estimated time:

Capsule 01 (this)  →  10 min reading
Capsule 02         →  20 min + practice
Capsule 03         →  15 min + secrets setup
Capsule 04         →  20 min + practice
Capsule 05         →  15 min + cost calculation

Total: ~1.25-1.5 hours

Evidence of Success

Before advancing to Module 2 (Automated Code Review), you should be able to:

✅ Create a YAML workflow from scratch that runs Claude Code on pull requests, without copying templates
✅ Configure GitHub Secrets with your API key and reference it correctly in the YAML
✅ Identify which triggers are appropriate for the use case (PR vs push, with or without filters)
✅ Generate visible output in the PR — at least one comment or check with the analysis result
✅ Estimate the cost of a month of running the workflow for your team
✅ Diagnose a failing workflow by reading the Actions logs

If any of these isn't met by the end, go back to the corresponding capsule. Module 2 (Code Review) builds directly on these foundations — without a working workflow here, there's nothing to build on.

Summary

This module is the entry point to CI/CD for Claude Code
The key shift: from local to automatic — the agent works without you triggering it
GitHub Actions is the chosen platform because of its adoption and because it's the foundation of the complete pipeline
Secrets management is non-negotiable from the first commit
Costs matter — design for efficiency from the start, not as an afterthought
Useful output > ignored logs — the finding has to land in the PR
The difference between the "Monday 16:00 with merge" and "Monday 11:00 with merge" in the opening scenario is exactly what this module teaches

Next capsule: 02 — Your first YAML workflow. We start with the anatomy of a GitHub Actions workflow and build one step by step that runs Claude Code on every PR. No theoretical ceremony — code you copy, run, and watch work.

Additional Resources

GitHub Actions Documentation — Complete official documentation
GitHub Actions Workflow Syntax — YAML syntax reference
Anthropic API Documentation — How Claude Code authenticates in CI
Claude Code SDK Headless — The technical layer we'll use in CI
GitHub Secrets Documentation — How to handle secrets correctly
GitHub Octoverse 2025 — Adoption data for GitHub Actions and CI/CD

Next →Your First YAML Workflow with Claude Code

Module 1: Claude Code in GitHub Actions

Module 1: Claude Code in GitHub Actions

Overview

Where We Are in the Guide

The Mental Shift: From Local to Automatic

A Real Task: Before and After

Approach A: Without CI/CD (what many teams do today)

Approach B: With GitHub Actions (what you learn here)

Prerequisites

Required knowledge:

Recommended:

NOT required:

Module Roadmap

Capsule 01 — Module introduction (this capsule)

Capsule 02 — Your first YAML workflow

Capsule 03 — Secrets management with GitHub Secrets

Capsule 04 — Parsing output and generating artifacts

Capsule 05 — Costs and rate limiting

Progression map

What You'll Achieve in This Module

The before and after

What This Module Does NOT Cover

Pitfalls to Avoid While Taking This Module

1. "Hardcoding the API key in the YAML 'temporarily'"

2. "Configuring triggers on push with no filters"

3. "Ignoring costs because 'Claude Code is cheap'"

4. "Output as a log nobody reads"

5. "Treating the workflow as throwaway code"

Diagnosis: What's Your Starting Point?

How to Work Through This Module

Estimated time:

Evidence of Success

Summary

Additional Resources