feat: add flexible bot access control with allowed_bots option (#117)

* feat: skip permission check for GitHub App bot users

GitHub Apps (users ending with [bot]) now bypass permission checks
as they have their own authorization mechanism.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: add allow_bot_users option to control bot user access

- Add allow_bot_users input parameter (default: false)
- Modify checkHumanActor to optionally allow bot users
- Add comprehensive tests for bot user handling
- Improve security by blocking bot users by default

This change prevents potential prompt injection attacks from bot users
while providing flexibility for trusted bot integrations.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: mark bot user support feature as completed in roadmap

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: move allowedBots parameter to context object

Move allowedBots from function parameter to context.inputs to maintain
consistency with other input handling throughout the codebase.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: update README for bot user support feature

Add documentation for the new allowed_bots parameter that enables
bot users to trigger Claude actions with granular control.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: add missing allowedBots property in permissions test

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: update bot name format to include [bot] suffix in tests and docs

- Update test cases to use correct bot actor names with [bot] suffix
- Update documentation example to show correct bot name format
- Align with GitHub's actual bot naming convention

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: normalize bot names for allowed_bots validation

- Strip [bot] suffix from both actor names and allowed bot list for comparison
- Allow both "dependabot" and "dependabot[bot]" formats in allowed_bots input
- Display normalized bot names in error messages for consistency
- Add comprehensive test coverage for both naming formats

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

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

@@ -23,6 +23,10 @@ inputs:
     description: "The prefix to use for Claude branches (defaults to 'claude/', use 'claude-' for dash format)"
     required: false
     default: "claude/"
+  allowed_bots:
+    description: "Comma-separated list of allowed bot usernames, or '*' to allow all bots. Empty string (default) allows no bots."
+    required: false
+    default: ""
 
   # Mode configuration
   mode:
@@ -156,6 +160,7 @@ runs:
         OVERRIDE_PROMPT: ${{ inputs.override_prompt }}
         MCP_CONFIG: ${{ inputs.mcp_config }}
         OVERRIDE_GITHUB_TOKEN: ${{ inputs.github_token }}
+        ALLOWED_BOTS: ${{ inputs.allowed_bots }}
         GITHUB_RUN_ID: ${{ github.run_id }}
         USE_STICKY_COMMENT: ${{ inputs.use_sticky_comment }}
         DEFAULT_WORKFLOW_TOKEN: ${{ github.token }}

docs/security.md

@@ -3,7 +3,7 @@
 ## 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 User Control**: By default, GitHub Apps and bots cannot trigger this action for security reasons. Use the `allowed_bots` parameter to enable specific bots or all bots
 - **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

docs/usage.md

@@ -42,6 +42,8 @@ jobs:
           # Optional: grant additional permissions (requires corresponding GitHub token permissions)
           # additional_permissions: |
           #   actions: read
+          # Optional: allow bot users to trigger the action
+          # allowed_bots: "dependabot[bot],renovate[bot]"
 ```
 
 ## Inputs
@@ -76,6 +78,7 @@ jobs:
 | `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`   |
+| `allowed_bots`                 | Comma-separated list of allowed bot usernames, or '\*' to allow all bots. Empty string (default) allows no bots                       | No       | ""        |
 
 \*Required when using direct Anthropic API (default and when not using Bedrock or Vertex)
 

src/github/context.ts

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

src/github/validation/actor.ts

@@ -21,9 +21,42 @@ export async function checkHumanActor(
 
   console.log(`Actor type: ${actorType}`);
 
+  // Check bot permissions if actor is not a User
   if (actorType !== "User") {
+    const allowedBots = githubContext.inputs.allowedBots;
+
+    // Check if all bots are allowed
+    if (allowedBots.trim() === "*") {
+      console.log(
+        `All bots are allowed, skipping human actor check for: ${githubContext.actor}`,
+      );
+      return;
+    }
+
+    // Parse allowed bots list
+    const allowedBotsList = allowedBots
+      .split(",")
+      .map((bot) =>
+        bot
+          .trim()
+          .toLowerCase()
+          .replace(/\[bot\]$/, ""),
+      )
+      .filter((bot) => bot.length > 0);
+
+    const botName = githubContext.actor.toLowerCase().replace(/\[bot\]$/, "");
+
+    // Check if specific bot is allowed
+    if (allowedBotsList.includes(botName)) {
+      console.log(
+        `Bot ${botName} is in allowed list, skipping human actor check`,
+      );
+      return;
+    }
+
+    // Bot not allowed
     throw new Error(
-      `Workflow initiated by non-human actor: ${githubContext.actor} (type: ${actorType}).`,
+      `Workflow initiated by non-human actor: ${botName} (type: ${actorType}). Add bot to allowed_bots list or use '*' to allow all bots.`,
     );
   }
 

src/github/validation/permissions.ts

@@ -17,6 +17,12 @@ export async function checkWritePermissions(
   try {
     core.info(`Checking permissions for actor: ${actor}`);
 
+    // Check if the actor is a GitHub App (bot user)
+    if (actor.endsWith("[bot]")) {
+      core.info(`Actor is a GitHub App: ${actor}`);
+      return true;
+    }
+
     // Check permissions directly using the permission endpoint
     const response = await octokit.repos.getCollaboratorPermissionLevel({
       owner: repository.owner,

test/actor.test.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env bun
+
+import { describe, test, expect } from "bun:test";
+import { checkHumanActor } from "../src/github/validation/actor";
+import type { Octokit } from "@octokit/rest";
+import { createMockContext } from "./mockContext";
+
+function createMockOctokit(userType: string): Octokit {
+  return {
+    users: {
+      getByUsername: async () => ({
+        data: {
+          type: userType,
+        },
+      }),
+    },
+  } as unknown as Octokit;
+}
+
+describe("checkHumanActor", () => {
+  test("should pass for human actor", async () => {
+    const mockOctokit = createMockOctokit("User");
+    const context = createMockContext();
+    context.actor = "human-user";
+
+    await expect(
+      checkHumanActor(mockOctokit, context),
+    ).resolves.toBeUndefined();
+  });
+
+  test("should throw error for bot actor when not allowed", async () => {
+    const mockOctokit = createMockOctokit("Bot");
+    const context = createMockContext();
+    context.actor = "test-bot[bot]";
+    context.inputs.allowedBots = "";
+
+    await expect(checkHumanActor(mockOctokit, context)).rejects.toThrow(
+      "Workflow initiated by non-human actor: test-bot (type: Bot). Add bot to allowed_bots list or use '*' to allow all bots.",
+    );
+  });
+
+  test("should pass for bot actor when all bots allowed", async () => {
+    const mockOctokit = createMockOctokit("Bot");
+    const context = createMockContext();
+    context.actor = "test-bot[bot]";
+    context.inputs.allowedBots = "*";
+
+    await expect(
+      checkHumanActor(mockOctokit, context),
+    ).resolves.toBeUndefined();
+  });
+
+  test("should pass for specific bot when in allowed list", async () => {
+    const mockOctokit = createMockOctokit("Bot");
+    const context = createMockContext();
+    context.actor = "dependabot[bot]";
+    context.inputs.allowedBots = "dependabot[bot],renovate[bot]";
+
+    await expect(
+      checkHumanActor(mockOctokit, context),
+    ).resolves.toBeUndefined();
+  });
+
+  test("should pass for specific bot when in allowed list (without [bot])", async () => {
+    const mockOctokit = createMockOctokit("Bot");
+    const context = createMockContext();
+    context.actor = "dependabot[bot]";
+    context.inputs.allowedBots = "dependabot,renovate";
+
+    await expect(
+      checkHumanActor(mockOctokit, context),
+    ).resolves.toBeUndefined();
+  });
+
+  test("should throw error for bot not in allowed list", async () => {
+    const mockOctokit = createMockOctokit("Bot");
+    const context = createMockContext();
+    context.actor = "other-bot[bot]";
+    context.inputs.allowedBots = "dependabot[bot],renovate[bot]";
+
+    await expect(checkHumanActor(mockOctokit, context)).rejects.toThrow(
+      "Workflow initiated by non-human actor: other-bot (type: Bot). Add bot to allowed_bots list or use '*' to allow all bots.",
+    );
+  });
+
+  test("should throw error for bot not in allowed list (without [bot])", async () => {
+    const mockOctokit = createMockOctokit("Bot");
+    const context = createMockContext();
+    context.actor = "other-bot[bot]";
+    context.inputs.allowedBots = "dependabot,renovate";
+
+    await expect(checkHumanActor(mockOctokit, context)).rejects.toThrow(
+      "Workflow initiated by non-human actor: other-bot (type: Bot). Add bot to allowed_bots list or use '*' to allow all bots.",
+    );
+  });
+});

test/install-mcp-server.test.ts

@@ -37,6 +37,7 @@ describe("prepareMcpConfig", () => {
       useStickyComment: false,
       additionalPermissions: new Map(),
       useCommitSigning: false,
+      allowedBots: "",
     },
   };
 

test/mockContext.ts

@@ -28,6 +28,7 @@ const defaultInputs = {
   useStickyComment: false,
   additionalPermissions: new Map<string, string>(),
   useCommitSigning: false,
+  allowedBots: "",
 };
 
 const defaultRepository = {

test/permissions.test.ts

@@ -73,6 +73,7 @@ describe("checkWritePermissions", () => {
       useStickyComment: false,
       additionalPermissions: new Map(),
       useCommitSigning: false,
+      allowedBots: "",
     },
   });
 
@@ -126,6 +127,16 @@ describe("checkWritePermissions", () => {
     );
   });
 
+  test("should return true for bot user", async () => {
+    const mockOctokit = createMockOctokit("none");
+    const context = createContext();
+    context.actor = "test-bot[bot]";
+
+    const result = await checkWritePermissions(mockOctokit, context);
+
+    expect(result).toBe(true);
+  });
+
   test("should throw error when permission check fails", async () => {
     const error = new Error("API error");
     const mockOctokit = {

test/trigger-validation.test.ts

@@ -41,6 +41,7 @@ describe("checkContainsTrigger", () => {
           useStickyComment: false,
           additionalPermissions: new Map(),
           useCommitSigning: false,
+          allowedBots: "",
         },
       });
       expect(checkContainsTrigger(context)).toBe(true);
@@ -74,6 +75,7 @@ describe("checkContainsTrigger", () => {
           useStickyComment: false,
           additionalPermissions: new Map(),
           useCommitSigning: false,
+          allowedBots: "",
         },
       });
       expect(checkContainsTrigger(context)).toBe(false);
@@ -291,6 +293,7 @@ describe("checkContainsTrigger", () => {
           useStickyComment: false,
           additionalPermissions: new Map(),
           useCommitSigning: false,
+          allowedBots: "",
         },
       });
       expect(checkContainsTrigger(context)).toBe(true);
@@ -325,6 +328,7 @@ describe("checkContainsTrigger", () => {
           useStickyComment: false,
           additionalPermissions: new Map(),
           useCommitSigning: false,
+          allowedBots: "",
         },
       });
       expect(checkContainsTrigger(context)).toBe(true);
@@ -359,6 +363,7 @@ describe("checkContainsTrigger", () => {
           useStickyComment: false,
           additionalPermissions: new Map(),
           useCommitSigning: false,
+          allowedBots: "",
         },
       });
       expect(checkContainsTrigger(context)).toBe(false);