Axon Shaft docs

GitHub App permissions

Each permission the AxonShaft GitHub App asks for, read or write, and what it's used for.

The AxonShaft app asks for these permissions when it's installed. A token minted for a run asks for only the part it needs, for that one repo.

PermissionAccessWhat it's used for
Organization: MembersRead-onlyThe dashboard reads your org membership to tell whether you're an org admin. Without it your role shows as Role unknown.
Repository: ContentsRead and writeThe run's token reads the repo. The push token for /fix and the dashboard's Add the workflow card write to it.
Repository: Pull requestsRead and writeThe run's token posts the summary comment, the review and its inline comments. Add workflow via PR opens a pull request.
Repository: IssuesRead and writeThe run's token asks for write, for comments and reactions, such as the /help reply on an issue.
Repository: WorkflowsRead and writeGitHub refuses any change under .github/workflows/ without it, so the dashboard needs it to add or update the workflow file.
Repository: ActionsRead-onlyThe run's token asks for it.
Repository: ChecksRead and writeA review's token posts Axon Shaft / review, a check run per checklist, and Axon Shaft / gates.
Repository: Code qualityRead and writeThe API reads GitHub Code Quality's findings for the Code quality findings checklist, with a read token only it holds. Nothing uses write yet.
Repository: Repository security advisoriesRead and writeThe API opens a private draft advisory for a blocking security finding, with a write token only it holds.
Repository: MetadataRead-onlyGitHub gives every app this.

The tokens a run gets

  • A review, /ask or /fix gets a token for its repo with Contents read, Pull requests and Issues write, and Actions read. A review's token also has Checks write.
  • A /fix whose checks pass gets a second token, with Contents write and nothing else, which the action revokes after the push.
  • Code quality and Repository security advisories never reach the runner.

What runs in CI says who holds each token.

New permissions

When the app asks for a new permission, each installation keeps its old set until its owner approves the new one on GitHub. Until then, a run's token leaves it out and the feature that needs it doesn't work: without Checks, for example, a review still posts its comments but no check runs. The job log warns once for each missing permission, and the dashboard shows the account's admin what's waiting. See Permissions to review.

Last updated on