How the `bump-plugin-shas.yml` Workflow Handles `GITHUB_TOKEN` Authorship

The bump-plugin-shas.yml workflow leverages the default GITHUB_TOKEN to author commits and pull requests as github-actions[bot], eliminating dedicated bot accounts while ensuring server-side signed commits and preventing workflow recursion.

The anthropics/claude-plugins-community repository automates plugin maintenance through a sophisticated GitHub Actions workflow that runs daily. This implementation demonstrates an elegant approach to GITHUB_TOKEN authorship that creates bump commits and PRs without requiring separate service accounts or manual signing key management.

The Bot-Free Authorship Model

The workflow is explicitly designed to operate without a dedicated bot account. According to the source code comments in .github/workflows/bump-plugin-shas.yml (lines 10-13), the bump commits and associated pull requests are authored by github-actions[bot], which represents the last pusher on the repository.

Because the workflow uses the default token provided by GitHub Actions rather than a personal access token (PAT), the automation inherits the built-in bot identity. This design choice allows human reviewers to merge the resulting PRs without triggering "last-pusher-can't-approve" restrictions that would occur if the PR author were the same account attempting to review it.

Token Permissions and Security Scopes

The workflow requests specific permissions to enable commit creation and PR management using the default token. In .github/workflows/bump-plugin-shas.yml (lines 43-46), the permissions block declares:

permissions:
  contents: write       # Required for createCommitOnBranch GraphQL mutation

  pull-requests: write    # Required to open PRs

  actions: write         # Required to dispatch validate-plugins.yml

These scopes allow the workflow to create signed commits via the GraphQL API and open pull requests without storing long-lived credentials. The actions: write permission specifically enables the workflow to trigger downstream validation jobs after creating bump PRs.

Server-Side Commit Signing with GraphQL

The createCommitOnBranch Mutation

The bump action creates cryptographically signed commits without managing GPG keys locally. In .github/actions/bump-plugin-shas/action.yml (lines 8-11), the implementation uses GitHub's GraphQL API to create commits server-side.

When using the default GITHUB_TOKEN, the createCommitOnBranch mutation automatically signs the commit according to the organization-level required_signatures rule. This occurs entirely on GitHub's infrastructure, eliminating the complexity of key storage and rotation.

The workflow executes a GraphQL mutation similar to this implementation:

gh api graphql -f query='
mutation($input:CreateCommitOnBranchInput!){
  createCommitOnBranch(input:$input){commit{oid}}
}' -f input='{
  "branch":"refs/heads/bump/plugin-name",
  "message":"Bump plugin SHA",
  "changes":[{
    "path":"plugins/plugin-name/sha",
    "contents":"new-sha-value"
  }]}' \
  -H "Authorization: bearer $GITHUB_TOKEN"

Recursion Guard and PR Trigger Behavior

A critical security feature of the default GITHUB_TOKEN is its inability to trigger new workflow runs through the on: pull_request event. As documented in .github/workflows/bump-plugin-shas.yml (lines 13-15), PRs opened with the default token do not fire the on: pull_request event.

This "recursion guard" prevents the workflow from triggering itself when it creates bump PRs. When a maintainer manually reviews and approves the PR, the Validate Plugins check defined in validate-plugins.yml can run properly, ensuring code quality without infinite loop risks.

Implementation Architecture

The workflow architecture separates concerns between the orchestrator and the action implementation. The main workflow file defines the schedule and permissions, while the local action handles the Git operations:

# From .github/workflows/bump-plugin-shas.yml

name: Bump Plugin SHAs

on:
  schedule:
    - cron: '0 0 * * *'  # Daily

  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write
  actions: write

jobs:
  bump:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/bump-plugin-shas
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The local action at .github/actions/bump-plugin-shas/action.yml encapsulates the bump logic, dependency installation, and GraphQL commit creation, ensuring the GITHUB_TOKEN authorship model remains consistent across all plugin updates.

Summary

• Default Token Authorship: The workflow uses the native GITHUB_TOKEN to author commits as github-actions[bot], avoiding PAT management.
• Scoped Permissions: contents: write, pull-requests: write, and actions: write enable commit creation and PR opening without excessive privileges.
• Server-Side Signing: The createCommitOnBranch GraphQL mutation creates verified commits automatically, satisfying required_signatures rules without local GPG keys.
• Recursion Prevention: Default token PRs don't trigger on: pull_request events, preventing workflow loops while allowing manual validation triggers.

Frequently Asked Questions

Why doesn't the workflow use a dedicated bot account?

The workflow intentionally avoids dedicated bot accounts to simplify credential management and permission auditing. By using the default GITHUB_TOKEN, the repository relies on GitHub's native github-actions[bot] identity, which inherits repository permissions automatically and doesn't require maintaining separate service account credentials or rotating personal access tokens.

How are the commits cryptographically signed without GPG keys?

The implementation uses GitHub's GraphQL API createCommitOnBranch mutation to create commits server-side rather than through local git operations. When authenticated with the default GITHUB_TOKEN, GitHub signs these commits automatically using its internal signing infrastructure, satisfying branch protection rules that require verified signatures without exposing signing keys to the runner environment.

What prevents the workflow from triggering itself infinitely?

The default GITHUB_TOKEN provided to workflow runs cannot trigger new workflow runs via the pull_request event. When bump-plugin-shas.yml creates a PR using this token, the on: pull_request event is suppressed (the recursion guard). This ensures the workflow doesn't enter an infinite loop of creating PRs that trigger more runs, while still allowing maintainers to trigger validation checks through manual review actions.

Why does the workflow need actions: write permission?

The actions: write permission allows the workflow to dispatch the validate-plugins.yml workflow after creating bump PRs. This scope enables the bump workflow to trigger downstream validation jobs programmatically, ensuring that plugin updates undergo automated testing before human review, all while operating under the same GITHUB_TOKEN authentication context.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}