Skip to content

Claude Code guide in three levels, Beginner to Advanced: hands-on lessons with checked exercises, every volatile fact cited to its source. Independent community guide.

17.5 KB
Raw Blame

GitHub Actions

Advanced · Lesson 5 of 7 · about 20 minutes, plus run time · Needs: Script Claude Code with claude -p · Verified against Claude Code v2.1.308 (stable) on 2026-10-25

Goal

By the end of this lesson you can run Claude Code unattended in a GitHub Actions workflow that reads its credential from a repository secret and stops within limits written in the file.

You need

  • The claude -p flags from lesson 4, such as --max-turns and --allowedTools.

  • The GitHub CLI, signed in with gh auth login.

  • A new private copy of the practice template, just for this lesson, which you own. Make it with:

    gh repo create claude-actions-practice --template wesammustafa/claude-code-practice --private --clone
    cd claude-actions-practice
    

    --template bases the new repository on the template, and --clone clones it (gh repo create). The check runs in this copy, with Node.js LTS, without --dir. At the end, you take the workflows and the secret out of it.

  • A credential: a Claude Console API key made for this lesson, recommended because the teardown deletes it, or, on a Pro, Max, Team or Enterprise plan, a token from claude setup-token (Manual setup).

  • Usage: light. Each run is short, and also uses GitHub Actions minutes (see Watch out).

The idea

The Claude Code GitHub Action, anthropics/claude-code-action (Anthropic), runs Claude Code as a step in a workflow. With no prompt input, it waits for @claude in an issue or pull request; with a prompt, it runs without waiting for a mention (Interactive and automation modes). Its display_report input puts Claude's report on the run's summary page (action.yml at v1.0.258).

The workflow names a repository secret that holds the credential (Manual setup). With github_token set to the job's own token, the action uses that token instead of the Claude GitHub App (Action parameters), so the job's permissions limit what it can do on GitHub (Workflow syntax).

No one is at the keyboard, so the limits go in the file. claude_args passes Claude Code's CLI flags, such as --max-turns and --allowedTools (Pass CLI arguments), and with a prompt written as text rather than a skill, Claude has no shell until you allow the commands it needs (Run on a schedule). The job's timeout-minutes limits its run time (Workflow syntax).

Worked example

Ask Claude a question from a workflow you start by hand. You set it up yourself, with a workflow file and a secret; the job's own token stands in for the Claude GitHub App, which this lesson doesn't install.

  1. In the copy, save this workflow as .github/workflows/ask-claude.yml, then commit it and push it to main. A manual run starts only when the workflow file is on the default branch (workflow_dispatch):

    name: Ask Claude
    on: workflow_dispatch
    jobs:
      ask:
        runs-on: ubuntu-latest
        timeout-minutes: 10
        permissions:
          contents: read
        steps:
          - uses: actions/checkout@v7
          - uses: anthropics/[email protected]
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              github_token: ${{ github.token }}
              prompt: "In one paragraph, what does src/links.js do? Don't change any files."
              claude_args: "--max-turns 3"
              display_report: true
    

    With a subscription token, replace the anthropic_api_key line with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} (Manual setup). Release v1.0.258 installs Claude Code v2.1.308 (run.ts at v1.0.258); its full commit SHA is 6b6870e649b5ff408753befeaee5fc7989d4e6a9.

  2. Save the credential as the repository secret the workflow names. With no value on the command line, gh secret set asks you to paste it (gh secret set):

    gh secret set ANTHROPIC_API_KEY
    gh secret list
    

    With a subscription token, run gh secret set CLAUDE_CODE_OAUTH_TOKEN instead. gh secret list then shows the secret's name (gh secret list). For a secret that several repositories will share, the docs recommend an API key, because a subscription token is tied to the subscription of the person who created it (Set up for an organization).

  3. Start the workflow, find its run, and follow it to the end (gh workflow run, gh run list, gh run watch):

    gh workflow run ask-claude.yml
    gh run list --workflow ask-claude.yml --limit 1
    gh run watch <run-id> --exit-status
    
  4. Open the run in your browser with gh run view <run-id> --web (gh run view). Its summary page holds Claude's report, with the answer. Your wording will differ, but it should describe how src/links.js finds Markdown links.

Both of the docs' setup paths install the Claude GitHub App (Setup). Its permission set is all or nothing, and includes write access to the repository's contents, issues, pull requests and workflows (GitHub App permissions), so install it only when you want @claude, with /install-github-app, or another Claude feature that needs it, such as Code Review.

Your turn

Brief: run Claude in CI with every limit written in the file, then leave no credential in the copy. Add .github/workflows/linkcheck-report.yml, a workflow you start by hand, in which Claude runs the template's link checker on samples/ and explains each broken link on the run's summary page, without changing any files. The docs' Run on a schedule example is a starting point. It sets a model with --model: pick one as in Intermediate lesson 3, or leave that line out to use Claude Code's default model (Pass CLI arguments).

Acceptance criteria:

  • It starts only by hand: on: workflow_dispatch, and no other trigger.
  • It uses anthropics/claude-code-action pinned to a release tag, such as @v1.0.258, or a full commit SHA, not @v1 (Watch out says why).
  • It has a prompt, so it runs in automation mode.
  • Its credential comes from the secret you saved, through the matching input, anthropic_api_key or claude_code_oauth_token. No credential is written in the file.
  • It has a read-only job token: the job's permissions grant contents: read and no write access, and github_token is set to the job's own token, as in the Worked example.
  • claude_args sets --max-turns to 10 or fewer, written as two words, --max-turns <n>, as the docs' Pass CLI arguments example does, and an --allowedTools rule for the link-check command alone, never all of Bash (Configure permissions).
  • The job has a timeout-minutes of 30 or fewer (Workflow syntax).
  • It checks out the repository and sets up Node.js before the action runs, as the template's .github/workflows/progress.yml does, so the link checker can run.
  • display_report is true, so Claude's report appears on the run's summary page. Turn it on only for trusted input, as here: you start the run, and the prompt and files are yours (action.yml at v1.0.258). Keep show_full_output off and don't turn on GitHub Actions debug mode: both print Claude's full output, which can include secrets, into the log (security notes).

Then run it, save the record and tear down:

  1. Commit the workflow and push it to main.

  2. Start it, find its id, follow it to the end and open it in your browser:

    gh workflow run linkcheck-report.yml
    gh run list --workflow linkcheck-report.yml --limit 1
    gh run watch <run-id> --exit-status
    gh run view <run-id> --web
    

    The run's summary page holds Claude's report, with its explanation of each broken link. Your wording will differ.

  3. Save the run record for the check, with the fields it reads (gh run list):

    mkdir -p .practice
    gh run list --workflow linkcheck-report.yml --json databaseId,status,conclusion,event,headSha,url,workflowName > .practice/a-5-runs.json
    
  4. Run npm run check -- a-5 (the Check below). When it passes, tear down: this is required. Don't tear down first: fixing a failed run needs the secret, which the teardown deletes.

[!WARNING] Deleting a secret leaves the credential it held valid (Uninstall). The CLAUDE_CODE_OAUTH_TOKEN secret holds an OAuth token of the kind claude setup-token generates (Action parameters). On 2026-10-24, a token from claude setup-token is valid for one year (Authentication), and deleting the secret doesn't revoke it.

  1. Delete both workflows, then commit and push:

    git rm .github/workflows/ask-claude.yml .github/workflows/linkcheck-report.yml
    git commit -m "Remove the Claude workflows"
    git push
    
  2. Delete the secret: gh secret delete ANTHROPIC_API_KEY, or gh secret delete CLAUDE_CODE_OAUTH_TOKEN (gh secret delete).

  3. With an API key, delete the key the secret held on the Claude Console's API keys page. With a subscription token, nothing in this teardown revokes it, so it stays valid until it expires (Uninstall): that's why this lesson recommends an API key.

If you installed the Claude GitHub App for this copy, also remove the copy from the App's repository access on GitHub (Modifying repository access).

Check

You are done when all of these are true:

  • A committed workflow runs anthropics/claude-code-action pinned to a release tag or a full commit SHA, in automation mode, with its credential from a secret and none in the file.
  • Its limits are in the file: --max-turns of 10 or fewer, an --allowedTools list without unrestricted Bash, a read-only job token (no write access in permissions) and a timeout-minutes of 30 or fewer.
  • .practice/a-5-runs.json shows a completed, successful manual run on a commit that holds the workflow.
  • Self-check (not tested): you can say who can start a Claude run in this copy, and which text from an issue or comment would reach Claude as input if you added an @claude workflow (see Watch out).

Run npm run check -- a-5 in this copy.

If the first or second item fails, its hint names the line or the limit to fix. If the saved run failed, gh run view <run-id> --log-failed shows why, such as a secret name that doesn't match the workflow; push a fix, run the workflow again and save the record again.

The check reads the workflow from your history, so it still passes after the teardown. Once it passes, tear down as Your turn's steps 5 to 7 describe.

Watch out

  • Anyone with write access to the repository can start a run with @claude, and the issue or comment text is input to Claude, so it can carry hidden instructions (Who can trigger runs, the action's security notes). Keep this copy private and yours: only people with read access can see its run logs (Using workflow run logs).
  • Each run uses GitHub Actions minutes and tokens. In a private repository, the minutes come out of your account's included minutes (GitHub Actions billing). The template's Progress workflow also runs on each push to this copy, so every push uses some of those minutes too. The tokens are billed to your Console account with an API key, or drawn from your plan with a subscription token. --max-turns and timeout-minutes limit how much work a run can do, which lowers both (Manage costs).
  • The v1 tag in the docs' examples moves to each new release (tags), and each release pins the Claude Code version it installs, so a workflow on @v1 can run a newer Claude Code than you tested. GitHub calls a workflow dependency lockfile the strongest protection, offers pinning to a full-length commit SHA for repositories that cannot adopt one, and warns that a tag can be moved or deleted if a bad actor gains access to the action's repository (Secure use reference). A release tag such as v1.0.258 is the lighter pin this lesson also accepts.

Listings checked against the listing bar on 2026-10-24.

Go further

  • Code Review: Anthropic's managed review of your pull requests, for Team and Enterprise plans, with no workflow to maintain.
  • Set up for an organization: one App install and one organization secret for many repositories, or workload identity federation in place of a stored key.
  • The action's solutions guide (Anthropic): complete workflows for pull request reviews, scheduled maintenance and issue triage.

Sources: Claude Code GitHub Actions · Authentication · Configure permissions · claude-code-action at v1.0.258: action.yml, run.ts, security, and its tags · GitHub: Events that trigger workflows, Workflow syntax, Secure use reference, Using workflow run logs, Reviewing and modifying installed GitHub Apps, GitHub Actions billing · GitHub CLI manual: gh repo create, gh secret set, gh secret list, gh workflow run, gh run list, gh run watch, gh run view, gh secret delete

← Script Claude Code with claude -p · Advanced index · Share your setup with a team → · Topic: Automation · Stuck on this lesson?