Axon Shaft docs

The workflow file

Every line of the workflow that runs Axon Shaft, why it runs on pull_request_target, and how to pin or update the action.

This is the workflow the dashboard gives. Its Add the workflow card commits it as .github/workflows/shaft.yml, but Axon Shaft finds it under any file name in .github/workflows/ on the default branch.

.github/workflows/shaft.yml
name: Axon Shaft
on:
  # pull_request_target, so a fork's pull request gets an OIDC token too. The action never runs the PR's code.
  pull_request_target:
    types: [opened, synchronize, reopened, ready_for_review]
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  pull_request_review:
    types: [submitted]
# A new push cancels the review of the commit before it. Comments each run on their own.
concurrency:
  group: axon-shaft-${{ github.event_name == 'pull_request_target' && github.event.pull_request.number || github.run_id }}
  cancel-in-progress: true
permissions:
  contents: read
  # The run's OIDC token is how the action signs in to Axon Shaft, which answers with
  # a GitHub token for this repo, the Claude token, the settings and the review prompt.
  id-token: write
jobs:
  axon-shaft:
    # Skip comments with no line that starts with /, and bots' comments (Axon Shaft's own included),
    # so they don't start a runner. The action picks out the command: /review, /fix, /ask, /axonshaft or /help.
    if: >-
      github.event_name == 'pull_request_target' ||
      (github.event.sender.type != 'Bot' &&
      contains(format('{0}{1}{0}{2}', fromJSON('"\n"'), github.event.comment.body, github.event.review.body), format('{0}/', fromJSON('"\n"'))))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          # Leaves no token in .git/config for the model to read.
          persist-credentials: false
      - uses: axonpack/shaft-actions@v1

The events

  • pull_request_target runs the review when a pull request is opened, pushed to (synchronize), reopened, or marked ready for review. Which of these start a review is the Code review's "When it runs" setting.
  • issue_comment, pull_request_review_comment and pull_request_review run the commands: /review, /ask, /fix, /axonshaft and /help, at the start of a line.

Why pull_request_target

GitHub gives a run on pull_request from a fork no OIDC token, so the action couldn't sign in and Axon Shaft would skip every fork's pull request with a notice. On pull_request_target, every pull request's run gets one, a fork's included.

pull_request_target runs the workflow file from the base branch, with the base branch checked out. The action then fetches the pull request's head commit and checks it out for the model to read. It never runs the pull request's code. Whether a fork's pull request is reviewed is the Code review's "Pull requests from forks" setting.

Concurrency

A new push to the same pull request cancels the review of the commit before it. Comments each get a group of their own (github.run_id), so two commands never cancel each other.

Permissions

  • contents: read is all the workflow's own token needs. Comments, reviews and check runs come from axonshaft[bot], through a token the API mints for the run.
  • id-token: write lets the action ask GitHub for the run's OIDC token, which is how it signs in to the Axon Shaft API. Without it the run fails with missing_id_token.

The if line

It skips comments that have no line starting with /, and comments from bots, Axon Shaft's own included, so they don't start a runner. Pull request events always run.

The steps

  • actions/checkout with persist-credentials: false leaves no token in .git/config for the model to read. /fix and /axonshaft refuse to run on a checkout that kept one (credentials_in_checkout). Add fetch-depth: 0 to give the model the whole history, so it can run git log and git diff against the base branch.
  • axonpack/shaft-actions@v1 is the action. Its only input is dry_run, which prints the summary and inline comments to the job log instead of posting them.
  • runs-on: ubuntu-latest: /fix and /axonshaft run only on GitHub-hosted runners (self_hosted_unsupported). Reviews and /ask run on any runner.

Pinning the action

  • @v1 gets each v1 release as it comes out. That's what the dashboard gives.
  • A release tag such as @v1.7.1 stays on that release until you change it. When a newer release is out, the summary comment shows a note under the card with links to update, and the project's Overview shows a New action version card.
  • A minor tag such as @v1.7 gets that minor's patches, and the card shows once a newer minor is out.

The New action version card can open a pull request that changes only the uses: axonpack/shaft-actions@ line, to @v1 or to the newest tag. When the dashboard's workflow changes, for example with a new trigger, the Overview shows a Workflow needs an update card that lists what's different and can open a pull request with the new file.

Last updated on