Permissions

A called reusable workflow cannot hold more GITHUB_TOKEN permissions than the caller grants, and most repos default to a read-only token. So workflows that need to write must have the caller grant it on the calling job. The stubs in examples/ already include the right permissions: blocks; copy them as-is.

Per-workflow grants

  • check-bibliography-dois, check-non-standard-chars, check-phi need only contents: read (the default), so no permissions: block is needed.
  • check-links opens an issue on main failures, so grant issues: write, pull-requests: read, contents: read.
  • summary comments on issues and calls the models API, so grant issues: write, models: read, contents: read.
  • update-snapshots pushes the snapshot-update commit back to the branch, so grant contents: write.
  • quarto-publish deploys to the gh-pages branch, so grant contents: write, and set Settings -> Pages -> Source to “Deploy from a branch”, branch gh-pages / (root) once. Grant contents: write even with deploy: false: the deploy job is part of the workflow, so the caller must grant its permissions even when it is skipped.
  • preview (build half, read-only) needs only contents: read (the default).
  • preview-deploy (deploy half) pushes gh-pages and comments, so grant contents: write, pull-requests: write, actions: read.
  • cleanup-pr-previews commits deletions to gh-pages, so grant contents: write, pull-requests: read.
  • bump-submodule, sync-shared-fragments, sync-upstream open a PR, so grant contents: write, pull-requests: write, and enable Settings -> Actions -> General -> “Allow GitHub Actions to create and approve pull requests”.
  • report-failure files or updates the issue tracking a failing workflow, so grant issues: write on the reporting job – and nothing else. It performs no checkout, so it needs no contents grant; the job it watches keeps its own permissions.
  • claude pushes branches, opens PRs, and dispatches the review workflow, so grant contents: write, pull-requests: write, issues: write, id-token: write, actions: write, and add either the CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY secret.
  • claude-code-review (read-only review) grants contents: read, pull-requests: write, issues: write, id-token: write, and either the CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY secret.
  • request-dependabot-review requests a reviewer on the PR, so grant pull-requests: write.
  • bump-dev-version opens (or auto-merges) a PR, so grant contents: write, pull-requests: write, enable the same “Allow GitHub Actions to create and approve pull requests” setting as above, and (for its default auto-merge: true) “Allow auto-merge” too. version-check is read-only, so grant only pull-requests: read, contents: read.

Optional secrets

  • WORKFLOW_TOKEN (a PAT or GitHub App token with contents:write + workflows:write). The integrated GITHUB_TOKEN cannot push changes to files under .github/workflows/; GitHub rejects them without the workflows scope. Add this secret if claude will edit workflow files, or to push to a protected branch. Unlike GITHUB_TOKEN, a PAT or App-token push does trigger other push-based workflows, so enabling it can set off extra CI runs. When the secret is absent and claude does edit a workflow file, the rejected push is reported as an error naming this secret, and the commits are posted to the thread as a git format-patch so they survive the run.
  • SUBMODULES_TOKEN. Public submodules clone anonymously; private ones need this secret. Relevant to claude, claude-code-review, and bump-submodule when checkout-submodules (or the submodule update) touches a private submodule.

Notes for private consumers

Reusable workflows in this public repo are callable from public repos automatically. A private consumer must allow access to this repo under Settings -> Actions -> General -> Access before it can call these workflows.