feat: add allow_bot_actor parameter for automated workflows

- Add allow_bot_actor parameter to enable GitHub bots to trigger Claude Code Action
- Implement robust bot write permission validation
- Use repo.permissions for comprehensive access checks
- Handle both collaborator and installation permissions
- Add comprehensive test coverage for bot scenarios
- Update documentation with security considerations

This enables automated workflows like documentation updates, CI-triggered
code reviews, and scheduled maintenance while maintaining security through
explicit opt-in and proper permission validation.

Author: lroolle

FAQ.md

@@ -6,7 +6,13 @@ This FAQ addresses common questions and gotchas when using the Claude Code GitHu
 
 ### Why doesn't tagging @claude from my automated workflow work?
 
-The `github-actions` user cannot trigger subsequent GitHub Actions workflows. This is a GitHub security feature to prevent infinite loops. To make this work, you need to use a Personal Access Token (PAT) instead, which will act as a regular user, or use a separate app token of your own. When posting a comment on an issue or PR from your workflow, use your PAT instead of the `GITHUB_TOKEN` generated in your workflow.
+By default, bots cannot trigger Claude for security reasons. With `allow_bot_actor: true`, you can enable bot triggers, but there are important distinctions:
+
+1. **GitHub Apps** (recommended): Create a GitHub App, use app tokens, and set `allow_bot_actor: true`. The app needs write permissions.
+2. **Personal Access Tokens**: Use a PAT instead of `GITHUB_TOKEN` in your workflows with `allow_bot_actor: true`.
+3. **github-actions[bot]**: Can trigger Claude with `allow_bot_actor: true`, BUT due to GitHub's security, responses won't trigger subsequent workflows.
+
+**Important**: With `allow_bot_actor: true`, `github-actions[bot]` CAN trigger Claude initially. However, Claude's responses (when using `GITHUB_TOKEN`) cannot trigger subsequent workflows due to GitHub's anti-loop security feature.
 
 ### Why does Claude say I don't have permission to trigger it?
 

README.md

@@ -145,8 +145,6 @@ jobs:
           # Or use OAuth token instead:
           # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          # Optional: set execution mode (default: tag)
-          # mode: "tag"
           # Optional: add custom trigger phrase (default: @claude)
           # trigger_phrase: "/claude"
           # Optional: add assignee trigger for issues
@@ -167,79 +165,41 @@ jobs:
 
 ## Inputs
 
-| Input                          | Description                                                                                                            | Required | Default   |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
-| `mode`                         | Execution mode: 'tag' (default - triggered by mentions/assignments), 'agent' (for automation with no trigger checking) | No       | `tag`     |
-| `anthropic_api_key`            | Anthropic API key (required for direct API, not needed for Bedrock/Vertex)                                             | No\*     | -         |
-| `claude_code_oauth_token`      | Claude Code OAuth token (alternative to anthropic_api_key)                                                             | No\*     | -         |
-| `direct_prompt`                | Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows)                  | No       | -         |
-| `override_prompt`              | Complete replacement of Claude's prompt with custom template (supports variable substitution)                          | No       | -         |
-| `base_branch`                  | The base branch to use for creating new branches (e.g., 'main', 'develop')                                             | No       | -         |
-| `max_turns`                    | Maximum number of conversation turns Claude can take (limits back-and-forth exchanges)                                 | No       | -         |
-| `timeout_minutes`              | Timeout in minutes for execution                                                                                       | No       | `30`      |
-| `use_sticky_comment`           | Use just one comment to deliver PR comments (only applies for pull_request event workflows)                            | No       | `false`   |
-| `github_token`                 | GitHub token for Claude to operate with. **Only include this if you're connecting a custom GitHub app of your own!**   | No       | -         |
-| `model`                        | Model to use (provider-specific format required for Bedrock/Vertex)                                                    | No       | -         |
-| `fallback_model`               | Enable automatic fallback to specified model when primary model is unavailable                                         | No       | -         |
-| `anthropic_model`              | **DEPRECATED**: Use `model` instead. Kept for backward compatibility.                                                  | No       | -         |
-| `use_bedrock`                  | Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API                                            | No       | `false`   |
-| `use_vertex`                   | Use Google Vertex AI with OIDC authentication instead of direct Anthropic API                                          | No       | `false`   |
-| `allowed_tools`                | Additional tools for Claude to use (the base GitHub tools will always be included)                                     | No       | ""        |
-| `disallowed_tools`             | Tools that Claude should never use                                                                                     | No       | ""        |
-| `custom_instructions`          | Additional custom instructions to include in the prompt for Claude                                                     | No       | ""        |
-| `mcp_config`                   | Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers                            | No       | ""        |
-| `assignee_trigger`             | The assignee username that triggers the action (e.g. @claude). Only used for issue assignment                          | No       | -         |
-| `label_trigger`                | The label name that triggers the action when applied to an issue (e.g. "claude")                                       | No       | -         |
-| `trigger_phrase`               | The trigger phrase to look for in comments, issue/PR bodies, and issue titles                                          | No       | `@claude` |
-| `branch_prefix`                | The prefix to use for Claude branches (defaults to 'claude/', use 'claude-' for dash format)                           | No       | `claude/` |
-| `claude_env`                   | Custom environment variables to pass to Claude Code execution (YAML format)                                            | No       | ""        |
-| `settings`                     | Claude Code settings as JSON string or path to settings JSON file                                                      | No       | ""        |
-| `additional_permissions`       | Additional permissions to enable. Currently supports 'actions: read' for viewing workflow results                      | No       | ""        |
-| `experimental_allowed_domains` | Restrict network access to these domains only (newline-separated).                                                     | No       | ""        |
-| `use_commit_signing`           | Enable commit signing using GitHub's commit signature verification. When false, Claude uses standard git commands      | No       | `false`   |
+| Input                          | Description                                                                                                          | Required | Default   |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
+| `anthropic_api_key`            | Anthropic API key (required for direct API, not needed for Bedrock/Vertex)                                           | No\*     | -         |
+| `claude_code_oauth_token`      | Claude Code OAuth token (alternative to anthropic_api_key)                                                           | No\*     | -         |
+| `direct_prompt`                | Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows)                | No       | -         |
+| `override_prompt`              | Complete replacement of Claude's prompt with custom template (supports variable substitution)                        | No       | -         |
+| `base_branch`                  | The base branch to use for creating new branches (e.g., 'main', 'develop')                                           | No       | -         |
+| `max_turns`                    | Maximum number of conversation turns Claude can take (limits back-and-forth exchanges)                               | No       | -         |
+| `timeout_minutes`              | Timeout in minutes for execution                                                                                     | No       | `30`      |
+| `use_sticky_comment`           | Use just one comment to deliver PR comments (only applies for pull_request event workflows)                          | No       | `false`   |
+| `github_token`                 | GitHub token for Claude to operate with. **Only include this if you're connecting a custom GitHub app of your own!** | No       | -         |
+| `model`                        | Model to use (provider-specific format required for Bedrock/Vertex)                                                  | No       | -         |
+| `fallback_model`               | Enable automatic fallback to specified model when primary model is unavailable                                       | No       | -         |
+| `anthropic_model`              | **DEPRECATED**: Use `model` instead. Kept for backward compatibility.                                                | No       | -         |
+| `use_bedrock`                  | Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API                                          | No       | `false`   |
+| `use_vertex`                   | Use Google Vertex AI with OIDC authentication instead of direct Anthropic API                                        | No       | `false`   |
+| `allowed_tools`                | Additional tools for Claude to use (the base GitHub tools will always be included)                                   | No       | ""        |
+| `disallowed_tools`             | Tools that Claude should never use                                                                                   | No       | ""        |
+| `custom_instructions`          | Additional custom instructions to include in the prompt for Claude                                                   | No       | ""        |
+| `mcp_config`                   | Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers                          | No       | ""        |
+| `assignee_trigger`             | The assignee username that triggers the action (e.g. @claude). Only used for issue assignment                        | No       | -         |
+| `label_trigger`                | The label name that triggers the action when applied to an issue (e.g. "claude")                                     | No       | -         |
+| `trigger_phrase`               | The trigger phrase to look for in comments, issue/PR bodies, and issue titles                                        | No       | `@claude` |
+| `branch_prefix`                | The prefix to use for Claude branches (defaults to 'claude/', use 'claude-' for dash format)                         | No       | `claude/` |
+| `claude_env`                   | Custom environment variables to pass to Claude Code execution (YAML format)                                          | No       | ""        |
+| `settings`                     | Claude Code settings as JSON string or path to settings JSON file                                                    | No       | ""        |
+| `allow_bot_actor`              | Allow GitHub bots and automation accounts to trigger Claude (security: defaults to false, requires explicit opt-in)  | No       | `false`   |
+| `additional_permissions`       | Additional permissions to enable. Currently supports 'actions: read' for viewing workflow results                    | No       | ""        |
+| `experimental_allowed_domains` | Restrict network access to these domains only (newline-separated).                                                   | No       | ""        |
+| `use_commit_signing`           | Enable commit signing using GitHub's commit signature verification. When false, Claude uses standard git commands    | No       | `false`   |
 
 \*Required when using direct Anthropic API (default and when not using Bedrock or Vertex)
 
 > **Note**: This action is currently in beta. Features and APIs may change as we continue to improve the integration.
 
-## Execution Modes
-
-The action supports two execution modes, each optimized for different use cases:
-
-### Tag Mode (Default)
-
-The traditional implementation mode that responds to @claude mentions, issue assignments, or labels.
-
-- **Triggers**: `@claude` mentions, issue assignment, label application
-- **Features**: Creates tracking comments with progress checkboxes, full implementation capabilities
-- **Use case**: General-purpose code implementation and Q&A
-
-```yaml
-- uses: anthropics/claude-code-action@beta
-  with:
-    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-    # mode: tag is the default
-```
-
-### Agent Mode
-
-For automation and scheduled tasks without trigger checking.
-
-- **Triggers**: Always runs (no trigger checking)
-- **Features**: Perfect for scheduled tasks, works with `override_prompt`
-- **Use case**: Maintenance tasks, automated reporting, scheduled checks
-
-```yaml
-- uses: anthropics/claude-code-action@beta
-  with:
-    mode: agent
-    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-    override_prompt: |
-      Check for outdated dependencies and create an issue if any are found.
-```
-
-See [`examples/claude-modes.yml`](./examples/claude-modes.yml) for complete examples of each mode.
-
 ### Using Custom MCP Configuration
 
 The `mcp_config` input allows you to add custom MCP (Model Context Protocol) servers to extend Claude's capabilities. These servers merge with the built-in GitHub MCP servers.
@@ -871,7 +831,7 @@ Both AWS Bedrock and GCP Vertex AI require OIDC authentication.
 ### Access Control
 
 - **Repository Access**: The action can only be triggered by users with write access to the repository
-- **No Bot Triggers**: GitHub Apps and bots cannot trigger this action
+- **Bot Actor Control**: GitHub Apps and bots are blocked by default for security. Use `allow_bot_actor: true` to enable automated workflows (requires explicit opt-in)
 - **Token Permissions**: The GitHub app receives only a short-lived token scoped specifically to the repository it's operating in
 - **No Cross-Repository Access**: Each action invocation is limited to the repository where it was triggered
 - **Limited Scope**: The token cannot access other repositories or perform actions beyond the configured permissions

ROADMAP.md

@@ -10,7 +10,7 @@ Thank you for trying out the beta of our GitHub Action! This document outlines o
 - **Support for workflow_dispatch and repository_dispatch events** - Dispatch Claude on events triggered via API from other workflows or from other services
 - **Ability to disable commit signing** - Option to turn off GPG signing for environments where it's not required. This will enable Claude to use normal `git` bash commands for committing. This will likely become the default behavior once added.
 - **Better code review behavior** - Support inline comments on specific lines, provide higher quality reviews with more actionable feedback
-- **Support triggering @claude from bot users** - Allow automation and bot accounts to invoke Claude
+- ~**Support triggering @claude from bot users** - Allow automation and bot accounts to invoke Claude~
 - **Customizable base prompts** - Full control over Claude's initial context with template variables like `$PR_COMMENTS`, `$PR_FILES`, etc. Users can replace our default prompt entirely while still accessing key contextual data
 
 ---

action.yml

@@ -60,6 +60,10 @@ inputs:
     description: "Complete replacement of Claude's prompt with custom template (supports variable substitution)"
     required: false
     default: ""
+  allow_bot_actor:
+    description: "Allow bot actors to trigger the action. Default is false for security reasons."
+    required: false
+    default: "false"
   mcp_config:
     description: "Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers"
   additional_permissions:
@@ -154,6 +158,7 @@ runs:
         CUSTOM_INSTRUCTIONS: ${{ inputs.custom_instructions }}
         DIRECT_PROMPT: ${{ inputs.direct_prompt }}
         OVERRIDE_PROMPT: ${{ inputs.override_prompt }}
+        ALLOW_BOT_ACTOR: ${{ inputs.allow_bot_actor }}
         MCP_CONFIG: ${{ inputs.mcp_config }}
         OVERRIDE_GITHUB_TOKEN: ${{ inputs.github_token }}
         GITHUB_RUN_ID: ${{ github.run_id }}

src/entrypoints/prepare.ts

@@ -51,7 +51,7 @@ async function run() {
       return;
     }
 
-    // Step 5: Check if actor is human
+    // Step 5: Check if actor is human (unless bot actors are allowed)
     await checkHumanActor(octokit.rest, context);
 
     // Step 6: Create initial tracking comment (mode-aware)

src/github/context.ts

@@ -43,6 +43,7 @@ export type ParsedGitHubContext = {
     useStickyComment: boolean;
     additionalPermissions: Map<string, string>;
     useCommitSigning: boolean;
+    allowBotActor: boolean;
   };
 };
 
@@ -81,6 +82,7 @@ export function parseGitHubContext(): ParsedGitHubContext {
         process.env.ADDITIONAL_PERMISSIONS ?? "",
       ),
       useCommitSigning: process.env.USE_COMMIT_SIGNING === "true",
+      allowBotActor: process.env.ALLOW_BOT_ACTOR === "true",
     },
   };
 

src/github/validation/actor.ts

@@ -5,22 +5,47 @@
  * Prevents automated tools or bots from triggering Claude
  */
 
+import * as core from "@actions/core";
 import type { Octokit } from "@octokit/rest";
 import type { ParsedGitHubContext } from "../context";
 
+/**
+ * Get the GitHub actor type (User, Bot, Organization, etc.)
+ */
+async function getActorType(
+  octokit: Octokit,
+  actor: string,
+): Promise<string | null> {
+  try {
+    const { data } = await octokit.users.getByUsername({ username: actor });
+    return data.type;
+  } catch (error) {
+    core.warning(`Failed to get user data for ${actor}: ${error}`);
+    return null;
+  }
+}
+
 export async function checkHumanActor(
   octokit: Octokit,
   githubContext: ParsedGitHubContext,
 ) {
-  // Fetch user information from GitHub API
-  const { data: userData } = await octokit.users.getByUsername({
-    username: githubContext.actor,
-  });
+  const actorType = await getActorType(octokit, githubContext.actor);
 
-  const actorType = userData.type;
+  if (!actorType) {
+    throw new Error(
+      `Could not determine actor type for: ${githubContext.actor}`,
+    );
+  }
 
   console.log(`Actor type: ${actorType}`);
 
+  if (githubContext.inputs.allowBotActor && actorType === "Bot") {
+    console.log(
+      `Bot actor allowed, skipping human actor check for: ${githubContext.actor}`,
+    );
+    return;
+  }
+
   if (actorType !== "User") {
     throw new Error(
       `Workflow initiated by non-human actor: ${githubContext.actor} (type: ${actorType}).`,