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

README.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
 
 ---

ROADMAP.md

@@ -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 }}

action.yml

@@ -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?
 

docs/faq.md

@@ -7,60 +7,40 @@
 
 import * as core from "@actions/core";
 import { setupGitHubToken } from "../github/token";
+import { checkHumanActor } from "../github/validation/actor";
 import { checkWritePermissions } from "../github/validation/permissions";
+import { createInitialComment } from "../github/operations/comments/create-initial";
+import { setupBranch } from "../github/operations/branch";
+import { configureGitAuth } from "../github/operations/git-config";
+import { prepareMcpConfig } from "../mcp/install-mcp-server";
 import { createOctokit } from "../github/api/client";
-import { parseGitHubContext, isEntityContext } from "../github/context";
-import { getMode, isValidMode, DEFAULT_MODE } from "../modes/registry";
-import type { ModeName } from "../modes/types";
-import { prepare } from "../prepare";
+import { fetchGitHubData } from "../github/data/fetcher";
+import { parseGitHubContext } from "../github/context";
+import { getMode } from "../modes/registry";
+import { createPrompt } from "../create-prompt";
 
 async function run() {
   try {
-    // Step 1: Get mode first to determine authentication method
-    const modeInput = process.env.MODE || DEFAULT_MODE;
-
-    // Validate mode input
-    if (!isValidMode(modeInput)) {
-      throw new Error(`Invalid mode: ${modeInput}`);
-    }
-    const validatedMode: ModeName = modeInput;
-
-    // Step 2: Setup GitHub token based on mode
-    let githubToken: string;
-    if (validatedMode === "experimental-review") {
-      // For experimental-review mode, use the default GitHub Action token
-      githubToken = process.env.DEFAULT_WORKFLOW_TOKEN || "";
-      if (!githubToken) {
-        throw new Error(
-          "DEFAULT_WORKFLOW_TOKEN not found for experimental-review mode",
-        );
-      }
-      console.log("Using default GitHub Action token for review mode");
-      core.setOutput("GITHUB_TOKEN", githubToken);
-    } else {
-      // For other modes, use the existing token exchange
-      githubToken = await setupGitHubToken();
-    }
+    // Step 1: Setup GitHub token
+    const githubToken = await setupGitHubToken();
     const octokit = createOctokit(githubToken);
 
     // Step 2: Parse GitHub context (once for all operations)
     const context = parseGitHubContext();
 
-    // Step 3: Check write permissions (only for entity contexts)
-    if (isEntityContext(context)) {
-      const hasWritePermissions = await checkWritePermissions(
-        octokit.rest,
-        context,
+    // Step 3: Check write permissions
+    const hasWritePermissions = await checkWritePermissions(
+      octokit.rest,
+      context,
+    );
+    if (!hasWritePermissions) {
+      throw new Error(
+        "Actor does not have write permissions to the repository",
       );
-      if (!hasWritePermissions) {
-        throw new Error(
-          "Actor does not have write permissions to the repository",
-        );
-      }
     }
 
     // Step 4: Get mode and check trigger conditions
-    const mode = getMode(validatedMode, context);
+    const mode = getMode(context.inputs.mode);
     const containsTrigger = mode.shouldTrigger(context);
 
     // Set output for action.yml to check
@@ -71,16 +51,65 @@ async function run() {
       return;
     }
 
-    // Step 5: Use the new modular prepare function
-    const result = await prepare({
-      context,
-      octokit,
-      mode,
-      githubToken,
+    // 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)
+    // Some modes (e.g., agent mode) may not need tracking comments
+    let commentId: number | undefined;
+    let commentData:
+      | Awaited<ReturnType<typeof createInitialComment>>
+      | undefined;
+    if (mode.shouldCreateTrackingComment()) {
+      commentData = await createInitialComment(octokit.rest, context);
+      commentId = commentData.id;
+    }
+
+    // Step 7: Fetch GitHub data (once for both branch setup and prompt creation)
+    const githubData = await fetchGitHubData({
+      octokits: octokit,
+      repository: `${context.repository.owner}/${context.repository.repo}`,
+      prNumber: context.entityNumber.toString(),
+      isPR: context.isPR,
+      triggerUsername: context.actor,
     });
 
-    // Set the MCP config output
-    core.setOutput("mcp_config", result.mcpConfig);
+    // Step 8: Setup branch
+    const branchInfo = await setupBranch(octokit, githubData, context);
+
+    // Step 9: Configure git authentication if not using commit signing
+    if (!context.inputs.useCommitSigning) {
+      try {
+        await configureGitAuth(githubToken, context, commentData?.user || null);
+      } catch (error) {
+        console.error("Failed to configure git authentication:", error);
+        throw error;
+      }
+    }
+
+    // Step 10: Create prompt file
+    const modeContext = mode.prepareContext(context, {
+      commentId,
+      baseBranch: branchInfo.baseBranch,
+      claudeBranch: branchInfo.claudeBranch,
+    });
+
+    await createPrompt(mode, modeContext, githubData, context);
+
+    // Step 11: Get MCP configuration
+    const additionalMcpConfig = process.env.MCP_CONFIG || "";
+    const mcpConfig = await prepareMcpConfig({
+      githubToken,
+      owner: context.repository.owner,
+      repo: context.repository.repo,
+      branch: branchInfo.claudeBranch || branchInfo.currentBranch,
+      baseBranch: branchInfo.baseBranch,
+      additionalMcpConfig,
+      claudeCommentId: commentId?.toString() || "",
+      allowedTools: context.inputs.allowedTools,
+      context,
+    });
+    core.setOutput("mcp_config", mcpConfig);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     core.setFailed(`Prepare step failed with error: ${errorMessage}`);

src/entrypoints/prepare.ts

@@ -77,6 +77,7 @@ type BaseContext = {
     useStickyComment: boolean;
     additionalPermissions: Map<string, string>;
     useCommitSigning: boolean;
+    allowBotActor: boolean;
   };
 };
 
@@ -136,6 +137,7 @@ export function parseGitHubContext(): GitHubContext {
         process.env.ADDITIONAL_PERMISSIONS ?? "",
       ),
       useCommitSigning: process.env.USE_COMMIT_SIGNING === "true",
+      allowBotActor: process.env.ALLOW_BOT_ACTOR === "true",
     },
   };
 

src/github/context.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}).`,