---
title: How do you govern Claude Code running in GitHub Actions?
url: https://opencontroller.lyzr.com/blog/govern-claude-code-github-actions
published: 2026-11-16
updated: 2026-11-16
author: Lyzr
---

# How do you govern Claude Code running in GitHub Actions?

**Govern Claude Code in GitHub Actions by controlling four things: who can trigger a run, what the GitHub App can touch, how the workflow authenticates to the model, and which tools Claude may use. Use OIDC federation instead of stored keys, grant tools explicitly with `--allowedTools`, cap work with `--max-turns` and timeouts, and keep a list of every repository running the action.**

The action is an agent with write access to your code. It deserves the same register-scope-monitor treatment as any production agent. For agent governance basics, see [what is an AI agent control plane](/blog/what-is-an-ai-agent-control-plane).

## How does the Claude Code GitHub Action run?

`anthropics/claude-code-action@v1` has two modes:

| Mode | Trigger | Where results go |
|---|---|---|
| Interactive | No `prompt` input; waits for `@claude` in an issue, PR comment, review or new issue | Comment on the issue or PR |
| Automation | `prompt` input set; runs on any GitHub event, including `schedule` | Workflow run log by default |

Automation mode is the riskier one. It runs without a human mention, on whatever events the workflow lists.

## Who can trigger a run?

The action checks the triggering actor before Claude starts:

- **Write access.** On issue and pull request events, the user must have write access to the repository. `allowed_non_write_users` relaxes this for named users.
- **Human actor.** Bot actors are rejected unless listed in `allowed_bots`. This stops bots triggering Claude in loops.

Governance rule: treat any use of `allowed_non_write_users` or `allowed_bots` as an exception that needs approval and a named owner.

On public repositories, GitHub withholds secrets from fork pull request runs, which limits outside triggers further.

## What permissions does the GitHub App get?

The official Claude GitHub App is shared by several Claude features, so installing it grants the full set:

| Permission | Access |
|---|---|
| Actions, Checks, Contents, Discussions, Issues, Pull requests, Repository hooks, Workflows | Read and write |
| Administration, Members, Merge queues, Metadata, Statuses | Read |

The action itself relies on three: **Contents, Issues and Pull requests**. GitHub does not let you accept a subset. If policy requires least privilege, create a **custom GitHub App** with only those three, as the action's setup guide describes. Other Claude features such as Code Review still need the official app.

## How should the workflow authenticate?

Options, from weakest to strongest governance:

1. **`CLAUDE_CODE_OAUTH_TOKEN`**: tied to one person's subscription. Avoid for shared org secrets.
2. **`ANTHROPIC_API_KEY`** as an org-level Actions secret: works, but a long-lived key to rotate and track. Deleting the GitHub secret does not revoke the key.
3. **Workload identity federation**: the action exchanges the workflow's GitHub OIDC token for Claude API access through a Console service account. Set `anthropic_federation_rule_id` and `anthropic_organization_id`, and grant `id-token: write`. No stored key.
4. **Cloud provider via OIDC**: `use_bedrock`, `use_vertex` or `use_foundry` route inference through your own Amazon Bedrock, Google Cloud Agent Platform or Microsoft Foundry account, with no static cloud credentials.

Options 3 and 4 also give you a clean identity per workflow for audit.

## How do you limit what Claude can do in a run?

- **Grant tools explicitly.** In automation mode with a plain prompt, Claude has no shell or GitHub API access until you grant tools with `--allowedTools` in `claude_args` or a `permissions.allow` rule in `settings`.
- **Prefer skills with declared tools.** A skill's `allowed-tools` frontmatter makes the tool grant reviewable in the repo.
- **Cap iterations** with `--max-turns`.
- **Set workflow timeouts** and GitHub concurrency limits to stop runaway jobs.
- **Pin the model** with `--model` so changes are deliberate.
- **Keep `CLAUDE.md` short and reviewed.** Claude reads it every run, and it shapes behaviour.
- **Require human review before merge.** Branch protection still applies to Claude's pull requests.

## What should a CI agent register record?

1. Repository and workflow file path
2. Mode (interactive or automation) and trigger events
3. GitHub App used (official or custom) and its permissions
4. Auth method and identity (service account, cloud role)
5. Allowed tools and MCP servers
6. Model, turn cap and timeout
7. Owner and cost centre

[Finding AI agents in CI/CD pipelines](/blog/find-ai-agents-in-ci-cd-pipelines) shows how to build this list by searching for `anthropics/claude-code-action` across your organization. For developer-side controls, see [enforcing Claude Code policy with hooks](/blog/enforce-claude-code-policy-with-hooks).

## What does it cost?

Each run uses **GitHub Actions minutes** and **model tokens**. Subscription OAuth tokens draw on that subscription instead of API billing. Track both per repository, because scheduled automation jobs run whether anyone reads the output or not.

## How Opencontroller does this

Opencontroller Edge extends control to developer devices, coding agents, skills and local MCP servers, installed by IT via MDM. In the cloud, Opencontroller supports agent workload identity federation, keeps a governed registry of agents and tools, and its LLM Gateway attributes cost per agent and per version. [Book a demo](https://www.lyzr.ai/book-demo/) to see coding agent governance.

## Frequently asked questions

**Does deleting the GitHub secret revoke the Claude API key?**
No. The credential stays valid. Delete or deactivate the key in the Claude Console as well.

**Can Claude run shell commands in a scheduled workflow by default?**
No. With a plain-text prompt, Claude has no shell or GitHub API access until tools are granted with `--allowedTools` or permission rules.

**Why use a custom GitHub App?**
The official app requests a broad shared permission set. A custom app with only Contents, Issues and Pull requests covers the action with least privilege.

## Key facts

The Claude Code GitHub Action (anthropics/claude-code-action@v1) runs in interactive mode (responds to @claude) or automation mode (runs a prompt on any event, including schedules). Before a run it checks that the triggering user has write access (configurable with allowed_non_write_users) and rejects bot actors unless listed in allowed_bots. The shared Claude GitHub App requests 13 permissions, including Contents, Issues, Pull requests and Workflows read-write; organizations can create a custom app with only Contents, Issues and Pull requests. Workload identity federation exchanges the GitHub OIDC token for Claude API access via a service account, avoiding stored keys; Bedrock, Google Cloud Agent Platform and Foundry also use OIDC. In automation mode with a plain prompt, Claude has no shell or GitHub API access until tools are granted via --allowedTools or permission rules. --max-turns and workflow timeouts cap cost. Opencontroller Edge extends control to coding agents. Opencontroller pricing starts from $250K per deployment per year.

## Related

- [How do you govern Claude Code across an enterprise?](https://opencontroller.lyzr.com/blog/govern-claude-code-in-the-enterprise.md)
- [How do you find AI agents running in CI/CD pipelines?](https://opencontroller.lyzr.com/blog/find-ai-agents-in-ci-cd-pipelines.md)
- [Can Claude Code hooks enforce security policy across an enterprise?](https://opencontroller.lyzr.com/blog/enforce-claude-code-policy-with-hooks.md)
- [More on Platform Guides](https://opencontroller.lyzr.com/blog/cluster/platform-guides)
