GitHub Actions: Mentioning Claude in a PR to Let It Work Independently

📚 Series Navigation: The previous article 43 Git Workflows taught you how to let Claude handle branches, write commits, and open PRs locally—all performed while you sit at your computer with Claude by your side. This article moves it to the cloud: once configured, you can simply type @claude in a GitHub issue or PR, and it will run independently to analyze code, make changes, and open PRs—without you even turning on your computer. This is the Claude Code GitHub Action.

Picture this scenario around 11:00 PM: you've already gone to bed when a message pops up in the team chat.

A colleague: "Have you reviewed X's PR? It's been stuck all day and we need to deploy tomorrow."

You: "I'm in bed. I'll review it first thing in the morning."

Colleague: "...tomorrow morning will be too late."

If you had configured Claude Code GitHub Actions in that repository beforehand, you could have saved yourself from countless nights like this: before you even wake up, a review automatically generated by Claude is already posted on the PR—highlighting a potential null pointer risk and two unhandled edge cases line-by-line. The colleague makes the changes and merges the PR.

Simply put, the Claude Code we discussed in the first 40+ chapters requires your presence, terminal open, and you watching it work. This article on GitHub Actions addresses a different need: letting it run independently of your computer, living inside GitHub's servers, and waking up with a simple @claude call. Whether you are traveling, sleeping, or in a meeting, it can still triage issues, review PRs, and fix bugs.

After reading this article, you will get:

• A brief explanation of what the Claude Code GitHub Action is and how it relates to the local Claude Code
• How the @claude mention triggers work—where you type it and how it knows to respond
• What the minimal runnable workflow YAML looks like and what each line does, ready for you to copy and use
• Three of the most practical use cases: automated code review, automated modifications based on issues, and scheduled cron tasks
• How to configure API keys/secrets securely in GitHub, avoiding the ultimate red line
• A hands-on practice with expected output: set it up in your own repository and verify it in 5 minutes

---

01 Understand First: It Is "Claude Code Living in GitHub"

Conclusion first: the GitHub Actions version of Claude Code is simply running your local Claude Code on GitHub's servers—triggered not by terminal commands, but by repository events (PRs opened, comments made, or scheduled crons).

If you recall the first 40+ chapters, Claude Code has always been used like this: you open a terminal on your machine, run claude, and interact with it to modify files. Its operation depends on "your presence"—you must keep your computer on, supervise it, and approve its actions.

GitHub Actions removes this dependency. The official definition is straightforward:

Claude Code GitHub Actions brings AI-powered automation to your GitHub workflows. Simply mention @claude in any PR or issue, and Claude can analyze your code, create pull requests, implement features, and fix bugs—all while adhering to your project's standards.

Analogy: Hiring a night-shift colleague who never sleeps. Your team has developers monitoring code during the day, but at night, no one is around. Now you hire a night-shift worker—they don't punch in, need no desk, and cost no salary (only billing by usage). Whenever someone @-mention them saying "review this PR" or "fix this bug," they pick up the task and post results back. You sleep, they work. The GitHub Actions version of Claude is that night-shift colleague, residing in GitHub's data centers.

Don't confuse this key point: this is not a new product; at its core, it is Claude Code. The official documentation clarifies that it is built on the Claude Agent SDK (discussed in Chapter 45), and it still reads the CLAUDE.md in your repository root (introduced in Chapter 18). This means the guidelines and conventions you set for your project are fully inherited by this night-shift colleague, matching your local setup.

In real scenarios, once configured, it enables:

• PRs opened, but no one is free to review—letting it review automatically, marking issues line-by-line
• Issues clearly described, but you don't have time to code—comment @claude implement this to have it open a PR implementing the feature
• CI failed at night with no one around—letting it analyze error messages and attempt a fix

💡 Summary in one sentence: The GitHub Actions version of Claude Code is Claude Code running on GitHub's servers, triggered by repository events; it requires no human presence, respects your CLAUDE.md, and behaves like an automated night-shift worker.

---

02 @claude Mentions: How You Summon It and How It Knows to Respond

The core usage—mention it in an issue or PR comment, and it starts working. This section breaks down: where you type, what you type, and how it responds.

Analogy: @-mentioning a colleague on duty in a group chat. In a busy team chat, off-topic discussions happen, but when you @-mention the colleague on duty with a specific request, they know "this is for me" and pick it up. @claude is exactly like this—it remains silent unless mentioned; once @-mentioned, it treats the comment as a task assigned to it.

Where can you type it? The official documentation lists the following locations:

• PR comment section (issue comments)
• Review comments on specific lines of code in PRs (pull request review comments)
• Issue descriptions or comments

What should you write? Just like assigning tasks to a human colleague—speak in plain language and be specific. E.g.:

@claude implement this feature based on the issue description
@claude how should user authentication be handled for this interface
@claude fix that TypeError in the user panel component

It translates to "implement this feature based on the issue description," "how should user authentication be handled for this interface," and "fix that TypeError in the user panel component." It automatically analyzes the context—reading the issue, checking related code, and parsing your CLAUDE.md—to respond appropriately: modifying code and opening a PR if requested, or replying to questions.

This connects with the rule from Chapter 15—the more specific the instructions, the less it drifts. Asking a human colleague "check this PR" yields a vastly different result than "review this PR, focusing on concurrency safety and SQL injection." The same applies to @claude; a vague "take a look" leads to generic scans, while pointing to "SQL injection vulnerabilities" focuses its efforts.

A common pitfall for beginners is explicitly highlighted in the troubleshooting docs:

Verify that your comment contains @claude (not /claude).

A common scenario: you configure the setup, type /claude review this on a PR, and wait five minutes with no response. You assume the API key is incorrect, wasting time checking variables. In the end, you realize you typed a slash instead of @—/claude is a slash command for your local terminal (Chapter 36), which represents nothing in GitHub comments. Cloud triggers look for @claude (the @ symbol), not a slash. Keeping this in mind saves troubleshooting time.

	Local Terminal (Chapters 1-43)	GitHub Actions (This Chapter)
Who triggers	You run claude and type	Repository events (comments, PRs, scheduled tasks)
How to summon it	Type directly, or use / slash commands	Comment @claude (using the @ symbol!)
Do you need to be present?	Yes, supervising all edits	No, it runs independently in the cloud
Where it runs	Your own machine	GitHub-hosted runner
Who approves?	You approve step-by-step	Unattended, following workflow configurations

💡 Summary in one sentence: Commenting @claude + a specific request in an issue or PR triggers it; it responds after reading the context and CLAUDE.md; never type /claude—the cloud triggers on the @ symbol, not a slash.

---

03 Setup: The Simplest Way Is "Automatic Installation" via One Command

Before @claude can respond, you must install the integration into your repository—consisting of three parts: a GitHub App (permitting Claude to read/write), a secret (your API key), and a workflow file (instructing GitHub when to summon Claude).

It sounds tedious, but the official tool provides an "automatic installation" shortcut. The easiest approach: run a single command in your local Claude Code terminal.

/install-github-app

Note—this /install-github-app is a slash command typed in your local claude session (yes, the slash commands from Chapter 36, which differ from the cloud @claude mention; don't confuse them). It launches a setup guide, which the official docs describe:

This command will guide you through the setup of the GitHub App and the required secrets.

Specifically, it handles three steps at once: installs the GitHub App, configures the ANTHROPIC_API_KEY secret, and adds the sample workflow file under .github/workflows/. Just follow the prompts.

However, two hard prerequisites must be met, emphasized by note blocks in the official documentation:

• You must be a repository administrator to install the GitHub App and add secrets.
• This quickstart method is only for direct Claude API users. If you use Amazon Bedrock or Google Vertex AI, please refer to the manual configuration section.

In plain English: first, you must be a repository administrator (admin role) to install Apps and add secrets—which is a GitHub security requirement, not Claude's restriction. Second, this shortcut serves only "direct Claude API" users; if your team routes through cloud platforms like AWS Bedrock or Google Vertex AI (third-party models discussed in Chapter 05), you must follow the manual setup, which is briefly touched upon at the end of this article.

What permissions does the GitHub App request? The official docs specify three read/write permissions:

• Contents: Read & write (to modify repository files)
• Issues: Read & write (to reply to issues)
• Pull requests: Read & write (to create PRs and push edits)

Analogy: Issuing an ID card to your night-shift colleague. These three permissions are the access rights on their ID card—giving them access to the "codebase" to edit files, the "issues section" to reply, and the "PRs section" to push changes. Without these rights, they stand outside unable to work; requesting more rights introduces security issues. These three are the minimum requirements, and they are exactly what the app requests.

If /install-github-app fails (due to connection blockages or permission errors), you can configure manually: install the App via https://github.com/apps/claude, configure secrets in repository Settings, and copy the workflow file from the official repo at examples/claude.yml. But use /install-github-app if possible—running the automated process is far simpler, whereas manual configuration requires navigating folders for sample files.

Installing the App and running workflow tasks online might require a VPN depending on your network settings.

💡 Summary in one sentence: The easiest setup is running /install-github-app locally inside claude to configure the App, secrets, and workflows automatically; this requires being a repository administrator and using the direct Claude API; access is restricted to three read/write scopes: Contents, Issues, and Pull requests.

---

04 The Workflow YAML: Scheduling the "Duty Roster"

Once installed, the file that dictates "when to wake up Claude" is the workflow file—a YAML placed under .github/workflows/. In this section, we'll break down the minimal config line-by-line.

Analogy: Scheduling a duty roster for the night shift. The workflow file is this roster, clarifying two things: when they must report to work (triggers) and what they do once active (steps). Without this roster, the colleague will never know when or what to perform.

Let's look at the minimal workflow provided by the official documentation to "respond to @claude comments":

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Don't be intimidated by YAML; it consists of four blocks, which translate simply:

Block 1: name: The name of this workflow, which will display on your GitHub Actions tab.

Block 2: on (when to trigger): The trigger conditions. Here, it triggers when an issue comment is created (issue_comment's created) or a line review comment is created (pull_request_review_comment's created)—meaning the workflow activates whenever a new comment is posted in issues or PRs.

Block 3: jobs (what to run): Defines a job named claude, running on runs-on: ubuntu-latest (GitHub's hosted Ubuntu runner)—keeping your code on GitHub's infrastructure, which aligns with the "secure by default" design.

Block 4: steps (the steps): The core step runs uses: anthropics/claude-code-action@v1 (the official action provided by Anthropic, version v1). Inside with, the anthropic_api_key secret is passed in (explained in the next section). The comment # Responds to @claude mentions reminds you that this handles comments mentioning @claude.

Here is the neat part: in this configuration, there is no check written to "only run if comment contains @claude". Why? Because version v1 automatically detects the mode. From the official docs:

The action now automatically detects if it should run in interactive mode (responding to @claude mentions) or autonomous mode (running immediately with a prompt) based on your configuration.

Simply put: if you specify a prompt argument, it runs in "autonomous mode"—executing immediately upon trigger (such as the code reviews in the next section); if no prompt is provided, it runs in "interactive mode"—only responding when @claude is mentioned in comments. The minimal configuration lacks a prompt, so it defaults to interactive mode, waiting for mentions.

⚠️ This is where developers upgrading from beta easily trip. Older configurations required manual declaration of mode: "tag" and direct_prompt; v1 deprecates these—removing mode (auto-detected) and renaming direct_prompt to prompt. If you find old configurations referencing @beta, mode:, or direct_prompt online, update them to the v1 syntax and don't copy-paste them.

Where do CLI parameters like --max-turns or --model go? The official tool provides claude_args—almost any Claude Code CLI parameter you use locally can be passed here:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Your instructions here"          # Optional: instructions for the action
    claude_args: "--max-turns 5 --model claude-sonnet-4-6"  # Optional: CLI arguments

Commonly used options in claude_args include:

Argument	What it does	Default
--max-turns	Maximum number of turns (to limit API spend)	10
--model	Which model to use (e.g., claude-opus-4-8)	Defaults to Sonnet
--allowedTools	Permitted tools (comma-separated)	—
--mcp-config	MCP configuration path (from Chapter 22)	—
--debug	Enables debug output, used for troubleshooting	Off

An official fact in the docs: Claude Code GitHub Actions defaults to Sonnet; if you want Opus 4.8, you must explicitly declare --model claude-opus-4-8 inside claude_args. Sonnet is sufficient for reviews and minor bug fixes; swap to Opus for large rewrites or complex reasoning (the "task delegation" logic from Chapter 30 applies here in the same way).

💡 Summary in one sentence: A workflow is the duty roster—on dictates when to work, and claude-code-action@v1 in steps defines what to do; v1 automatically detects the mode (runs autonomously with prompt, otherwise waits for @claude mentions); CLI parameters are passed under claude_args.

---

05 Three Practical Use Cases: Automated Reviews, Edits, and Cron Jobs

Summoning @claude is just the beginning. This section provides three ready-to-use workflows for the most common scenarios, detailing what they solve and how they are configured.

Use Case 1: Automated PR Reviews (Autonomous, No Mentions Needed)

This is the most common setup, and is the key to the night scenario from the beginning. It requires no mentions; whenever a PR is opened or updated, Claude reviews it autonomously.

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this pull request for code quality, correctness, and security."
          claude_args: "--max-turns 5"

Compared to the minimal setup, there are two differences: triggers are changed to pull_request's opened (PR created) and synchronize (PR updated), and a prompt is provided. Recall the "autonomous mode when prompt is set" rule—because prompt is specified, it runs autonomously to inspect "code quality, correctness, and security" upon trigger, without waiting for mentions. Whenever code is pushed, it reviews it automatically and posts feedback.

If you prefer a fully managed review experience without writing workflows, Anthropic provides a separate Code Review service (for Team/Enterprise plans). Enabling it automatically reviews every PR, marks issues by severity, and supports customization via REVIEW.md. This article focuses on running Claude in your own CI pipeline; the managed service is an alternative.

Use Case 2: Edits Based on Issues (Summoning via @claude)

This utilizes the minimal "respond to @claude" workflow from Section 04; the focus is what you type in the comment. Once the issue description is clear, comment:

@claude implement the feature based on this issue description

It reads the issue, related code, and CLAUDE.md, implements the feature on a new branch, and opens a PR for you to review. I once added a CSV export feature to an internal utility this way—describing columns and format in the issue and @-mentioning it. A PR was opened twenty minutes later, and I merged it after review, without ever opening the editor.

The same goes for fixing bugs:

@claude fix that TypeError in the user panel component

It locates the error, patches it, and updates the branch or opens a PR.

Use Case 3: Scheduled Tasks (Running on Cron)

This doesn't require active events; it triggers strictly on time—such as compiling a report of yesterday's commits and open issues every morning at 9:00 AM.

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model opus"

on: schedule paired with cron: "0 9 * * *" runs once daily at 9:00 AM (UTC), compiling summaries according to the prompt. These "unattended, scheduled" tasks are perfect for delegating to this night-shift worker.

A comparative summary of the three use cases:

Use Case	Trigger Method	Provide prompt?	Mode	Typical Scenario
Automated Review	pull_request (PR created/updated)	Yes	Autonomous (runs automatically)	Reviewing every PR automatically
Issue-based Edits	issue_comment (commenting @claude)	No	Interactive (waits for @claude)	Translating issues to code, fixing bugs
Scheduled Tasks	schedule (cron scheduler)	Yes	Autonomous (runs automatically)	Daily reports, scheduled checks

Keep the main rule in mind: providing a prompt runs autonomously; omitting prompt waits for @claude mentions. Clarify which behavior you want, and configure prompt accordingly.

💡 Summary in one sentence: Three practical use cases—automated PR reviews (autonomous with prompt), edits based on issues (interactive, triggered by @-mentions), and scheduled tasks (triggered by cron with prompt); they are combinations of trigger events and prompt declarations.

---

06 Secrets Security: The Red Line You Must Never Cross

You probably noticed this line in every workflow configuration:

anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

This section focuses on the security rules behind this line—which is the most critical part of this article. We configured the local ANTHROPIC_API_KEY in Chapter 04, noting that we would discuss CI configurations in Chapter 44; here it is.

Let's copy the official warning block exactly here:

Never submit API keys directly to your repository.

Why is this a red line? Because GitHub repositories—especially public ones—are visible to everyone. If you write your actual sk-ant-xxxx key into a YAML file and commit it, you are posting your wallet PIN on a bulletin board. Anyone who scrapes it can run API calls, leaving you with the bill. This happens daily on GitHub, as credential-scraping bots run constantly.

The only correct approach: use GitHub Secrets, never hard-code. The official documentation steps are clear:

• Add your API key as a repository secret named ANTHROPIC_API_KEY.
• Reference it in the workflow: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Analogy: Locking keys in a safe, leaving only a code in the YAML. GitHub Secrets serves as a safe built into the repository—encrypting the key so it never appears in logs or interfaces. Writing ${{ secrets.ANTHROPIC_API_KEY }} in the workflow is not the secret itself, but a reference saying "open the safe and grab the key named ANTHROPIC_API_KEY". The file can be committed or made public, as it contains no credentials.

How to store keys in the safe? Manually: navigate to repository Settings → Secrets and variables → Actions, click New repository secret, name it ANTHROPIC_API_KEY, and paste your actual key (obtained from the Claude Console, see Chapter 04). If you ran /install-github-app earlier, this was handled automatically.

This aligns with the security posture we've emphasized. Chapter 21 discussed prompt injection—where attackers hide instructions inside issue descriptions or PR comments to trick Claude. This is highly relevant in cloud automation, as Claude reads comments that can be posted by anyone. Adhere to these best practices:

❌ Risky Practices	✅ Secure Practices
Writing actual keys in YAML files	Storing in GitHub Secrets, referencing in YAML
Granting full permissions for convenience	Granting only necessary scopes (Contents / Issues / PR read & write)
Merging PRs opened by Claude directly	Reviewing changes yourself before merging
Allowing untrusted users to summon @claude in public repos	Remain alert to prompt injections, restricting triggers in sensitive repositories

The rule "review before merging" is worth emphasizing—no matter how good Claude performs, its PR is just a contribution, not an automated pass. From the official docs: "review Claude's suggestions before merging." A rule to maintain: treat any PR created by the cloud Claude as work submitted by an intern, never merging it without review just because "AI wrote it and it looks okay."

💡 Summary in one sentence: The ultimate secret security rule—never write keys in repository files; instead, save them in GitHub Secrets and reference them via ${{ secrets.ANTHROPIC_API_KEY }}; pair this with "minimum permissions + manual review + prompt injection awareness" to run it safely.

---

07 Action: Set It Up in Your Own Repository in 5 Minutes

Theory is nothing without practice. Let's install it into one of your own GitHub repositories and verify it works. Choose a scratch repository where you have administrator access (avoid production repos) to run this test, which operates independently of complex environments.

Prerequisite: You must be a repository administrator, use the direct Claude API, and have Claude Code set up locally. VPN access may be required to connect to GitHub and Claude servers depending on your region.

Step 1: Run the installation command in local Claude Code

Navigate to the scratch repository directory, start claude, and type:

/install-github-app

Expected: It launches a guide, directing you to authorize in the browser—selecting the target repository for the Claude GitHub App, confirming the three scopes (Contents / Issues / PRs read/write), and saving ANTHROPIC_API_KEY in repository Secrets. Follow the prompts until it confirms success and writes the workflow file.

Step 2: Confirm the workflow file exists

Check your repository; a new file should be present:

.github/workflows/claude.yml

Expected: The file exists, containing the minimal workflow from Section 04 (on: issue_comment + claude-code-action@v1). Its presence means the roster is set. If missing, the installation was incomplete; run /install-github-app again.

Step 3: Verify the secret is saved

Check repository Settings → Secrets and variables → Actions.

Expected: ANTHROPIC_API_KEY appears under Repository secrets (with the value hidden). Seeing the name means the secret is stored.

Step 4: Open a test issue and @-mention it

Create a new issue, write any title, and type a small task in the description, e.g.:

@claude add a line "Hello from Claude Code GitHub Actions" at the end of README, then open a PR

Expected:

• Under the repository's Actions tab, a workflow named Claude Code will show Running (spinning) or completed (green checkmark).
• After a minute or two (required to boot on the runner, fetch code, and execute), Claude posts a comment on the issue and opens a PR—adding the line to the README.
• Seeing this automated PR confirms the workflow works.

If nothing happens after a few minutes, troubleshoot using the official steps: check if you typed /claude instead of @claude, confirm the App is installed, verify the secret key exists, and check if Actions are disabled. The slash command error is the most common pitfall.

Step 5: Review and merge

Open the PR, review the diff as you would for an intern's work, verifying it only added the requested line. Merge once verified.

Running these steps walks you through the flow: "install App → configure secret → schedule workflow → summon it → automated PR created → review and merge." Setting up other repositories follows this exact routine, just adjusting trigger events and prompt values.

💡 Summary in one sentence: Setup takes five steps—run /install-github-app, check claude.yml presence, verify key in Secrets, create issue @-mentioning @claude, and review/merge the automated PR; running it once is more effective than memorizing configurations.

---

08 Summary

This article moved Claude Code to the cloud—shifting from "you must be present" to "it runs on @claude mentions," powered by GitHub Actions automation.

Let's review the core points:

What you want to do	What to use	Key points
Understand what it is	Claude Code living inside GitHub	Triggered by repository events, requires no human presence, respects CLAUDE.md
Summoning it	Comment @claude + specific instructions	Looks for the @ symbol, not /claude
Set it up	Run /install-github-app locally	Requires admin permissions + direct API; requests three read/write scopes
Configure trigger and behavior	YAML file under .github/workflows/	on defines trigger, parameters passed under claude_args; v1 auto-detects mode
Select use cases	Reviews, issue-based edits, scheduled tasks	Specifying prompt runs autonomously, omitting waits for @claude
Guard secrets	GitHub Secrets	Never hard-code; reference via ${{ secrets.* }} in YAML

You should now be able to: explain the difference between the GitHub Actions version of Claude Code and the local CLI, summon it via @claude comments (avoiding /claude), read and adjust a workflow YAML, choose configurations for reviews/edits/crons, save secrets securely, and install/verify the setup in your own repository. This cloud automation upgrades Claude from a desktop assistant to a 24-hour teammate.

Once Actions are configured, there is no need to stay up waiting for PR reviews—your night-shift teammate is on it; you can sleep.

Side note: if you use GitLab instead of GitHub, there is a GitLab CI/CD integration (currently in beta). The logic is identical—add a job in .gitlab-ci.yml, set a masked variable, and trigger via @claude mentions. Adapting the GitHub workflow discussed here to GitLab follows the official documentation.

---

The next chapter 45 "Agent SDK"—the GitHub Actions integration discussed here is built on the Claude Agent SDK. In other words, the ability to automatically open PRs on @claude mentions is powered by an SDK that allows you to integrate Claude Code into any program via code. GitHub Actions is just one out-of-the-box wrapper. The next chapter lifts the hood: what if you want automations beyond @claude mentions—such as building a custom AI customer agent, batch-processing 10,000 files, or embedding Claude into your internal admin portals, driving it directly via code? Think about it: GitHub Actions handles triggers and execution wrapper, but when you want to customize when it runs and where results go, it's time to dig a level deeper.

---

Recommended Reading

• Permission Configurations: How Loose or Strict Is Up to You
• Desktop App
• Four Most Common Tasks: Exploring Codebases, Fixing Bugs, Refactoring, Writing Tests