Why Signed Commits Are Used in the bump-plugin-shas.yml Workflow

Signed commits are required in the bump-plugin-shas workflow to satisfy the repository's organization-level required_signatures ruleset while avoiding the need to manage private signing keys in the CI environment.

The anthropics/claude-plugins-community repository maintains a curated marketplace of external plugins, each pinned to specific SHA commits for security and reproducibility. The scheduled workflow defined in .github/workflows/bump-plugin-shas.yml automates these updates, but must comply with strict cryptographic signing policies enforced on the main branch.

The required_signatures Policy on the Main Branch

The repository operates under an organization-level ruleset that mandates cryptographic verification for every commit merged into the main branch. According to the source code in .github/workflows/bump-plugin-shas.yml (lines 76-78), this required_signatures policy means that any automated commit—such as those bumping plugin SHAs—must be cryptographically signed to pass branch protection checks.

Without signed commits, the automated pull requests generated by the workflow would fail merge requirements, blocking security updates and maintenance releases.

Server-Side Commit Creation with createCommitOnBranch

Rather than configuring GPG keys or other signing mechanisms within the GitHub Actions runner, the workflow delegates commit creation to GitHub's servers. The custom action located at .github/actions/bump-plugin-shas/action.yml (lines 9-11) utilizes the GraphQL createCommitOnBranch mutation to generate commits.

This server-side approach offers two critical advantages:

• Cryptographic compliance: GitHub signs the commit internally using its own infrastructure, satisfying the required_signatures policy.
• Keyless operation: The CI job never handles private signing material, reducing the attack surface and eliminating secrets management overhead.

Avoiding Private Key Management in CI

Traditional automated signing would require storing a private GPG key or SSH signing key as a repository secret, then configuring Git to use it during the workflow execution. By leveraging createCommitOnBranch, the workflow avoids this complexity entirely. The commit is signed by GitHub's internal key before it ever reaches the repository, ensuring that the main branch history remains verifiable without exposing sensitive credentials to the runner environment.

Workflow Implementation Details

The workflow orchestrates the bumping process by invoking a local composite action that wraps the GraphQL mutation. Below is the relevant configuration from the workflow file:

# In .github/workflows/bump-plugin-shas.yml – the step that creates a signed commit

- uses: ./.github/actions/bump-plugin-shas
  id: bump
  with:
    # …other inputs…

    pr-mode: per-entry   # one PR per bumped plugin

The action description explicitly documents the signing behavior:

# In .github/actions/bump-plugin-shas/action.yml – description of the signed commit

# The bump commit is created via the GraphQL `createCommitOnBranch` mutation so it

# is signed server-side by GitHub and satisfies `required_signatures` rulesets

# without managing any signing key.

Frozen SHAs and Selective Updates

Not all plugins receive automatic signed commits during every workflow run. The repository maintains a .github/freeze-shas.txt file listing plugins whose SHAs are frozen, preventing automatic bumping. When a plugin is unfrozen and updated, the workflow generates a new signed commit only for that specific entry, ensuring that intentional updates are properly authenticated while frozen dependencies remain stable.

Summary

• Policy compliance: Signed commits satisfy the organization-level required_signatures ruleset enforced on the main branch.
• Security architecture: Using createCommitOnBranch shifts cryptographic signing to GitHub's servers, eliminating the need for private keys in CI.
• Operational integrity: The workflow can generate merge-ready pull requests without triggering signature-related branch protection failures.
• Selective application: Plugins listed in .github/freeze-shas.txt are excluded from the automated signing and bumping process.

Frequently Asked Questions

What GraphQL mutation does the workflow use to create signed commits?

The workflow uses the createCommitOnBranch GraphQL mutation. This server-side operation creates the commit directly within GitHub's infrastructure and signs it using GitHub's internal signing key, satisfying the required_signatures requirement without local key configuration.

Why doesn't the workflow use local Git signing with GPG?

Local signing would require storing a private GPG key as a repository secret and configuring the GitHub Actions runner to access it. By using server-side commit creation, the workflow avoids managing sensitive signing keys in the CI environment, reducing security risks and operational complexity.

How does the required_signatures ruleset affect pull requests?

The required_signatures ruleset requires every commit on the main branch to have a valid cryptographic signature. If the bump-plugin-shas workflow created unsigned commits, the resulting pull requests would fail branch protection checks and could not be merged. Server-side signing ensures these automated PRs meet the repository's security standards immediately upon creation.

What happens to plugins listed in freeze-shas.txt?

Plugins listed in .github/freeze-shas.txt are excluded from the automated bumping process. The workflow checks this file before generating updates, meaning no signed commits are created for frozen plugins until they are explicitly removed from the list. This prevents unauthorized or accidental updates to critical dependencies while maintaining the signing requirement for all changes that do occur.

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