All jobs

Set Least-Privilege Permissions on GitHub Actions Workflows

Yes. An agent reads each workflow, works out what its steps write with the token, adds read-only permissions with job-level grants where needed, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads every workflow and asks of each step one question: does it write anything through GITHUB_TOKEN? In a library like sindresorhus/execa there is one workflow, .github/workflows/main.yml, named CI, running on every push and pull_request with no branch filter. Its single test job fans out over a matrix of Node 26, 24 and 22 on ubuntu, macos and windows with fail-fast: false, nine cells in all. The steps are actions/cache@v6 on .lycheecache, actions/checkout@v7, actions/setup-node@v7, npm install (there is no lockfile, because .npmrc sets package-lock=false), a lycheeverse/lychee-action@v2 link check with fail: true that runs only on ubuntu with Node 26, npm run lint (xo) on that same cell, then npm run type (nz && tsc), npm run unit (c8 around node --test), and codecov/codecov-action@v4 with secrets.CODECOV_TOKEN. The word permissions appears nowhere in the file, so each run gets whatever the repository's default token permissions are, which on older repositories means write to contents, packages, pull requests and more. .github/ also holds codecov.yml and security.md, and there is no Dependabot configuration.

None of those steps writes to the repository with the token: cache restores and saves use the Actions cache, checkout reads, Codecov uploads with its own token, and lychee fails the job rather than posting a comment. So the agent adds a top-level permissions: contents: read and nothing else, and records in the pull request why no job needs more. Where a repository does have writing jobs, the agent keeps the top-level block read-only and grants per job: in a project like miniflux/v2, whose docker.yml pushes images with GITHUB_TOKEN to ghcr.io, that job alone gets packages: write, and a stale.yml that labels and closes pull requests gets pull-requests: write on its job, which is how that repository is already written. The rule is the same every time: read-only at the workflow level so a job added next year inherits it, and the smallest scope on the one job that needs it.

The agent checks its own work with two linters. actionlint catches YAML and expression mistakes, and zizmor reports an excessive-permissions finding for each workflow or job that runs with the default token; the agent runs it before and after so the pull request can show the finding count going to zero for that audit while nothing else changed. It does not need to run the nine-cell matrix itself, because the workflow it is editing runs on pull_request, so the pull request's own checks are the proof that a read-only token still lets every step pass.

What the agent does not change is the repository setting under Actions, General, Workflow permissions, which only an admin can switch to read-only. The pull request recommends that switch as the second half of the change, because a workflow block limits workflows that have one, and the setting limits everything else.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Set least-privilege permissions on every GitHub Actions workflow in this repository. Read each file under .github/workflows and, for every job, list which steps write through GITHUB_TOKEN: pushes, releases, package publishes, comments, labels, check runs or security events. Add a top-level permissions block of contents: read to every workflow, and where a job needs more, add a job-level block with only the scopes that job uses. Do not change triggers, steps or action versions. Run actionlint and zizmor before and after and keep both outputs. Open a pull request whose description has one row per workflow and job with the scopes granted and the step that needs each, and recommend switching the repository's default workflow permissions to read-only.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request touching only files under .github/workflows: for a one-workflow repository that is a two-line addition at the top of main.yml. The description has a table with one row per workflow and job, the scopes it now has and the step that needs each, plus the zizmor summary before and after with the excessive-permissions findings gone.

The run's record keeps the actionlint and zizmor output and the reasoning for each job, so a reviewer who wonders why the Codecov step needs no GITHUB_TOKEN scope can read the answer rather than work it out.

Before merging, a reviewer confirms the pull request's own CI run passed on every matrix cell under the new token, which is the real test, and then flips the repository's default workflow permissions to read-only in the settings page the description links to.

Run it on every Monday morning

Workflows get added and copied, and a new one rarely arrives with a permissions block. An automation with a schedule trigger, cron set to 0 9 * * 1 in the team's timezone, and this prompt starts one run a week against the Project's repository; a week with nothing to fix ends with a run that opens no pull request and says so.

A team that would rather catch it at review time points a github trigger on pull_request.opened and pull_request.synchronize at the same prompt with a first line telling the agent to look only at workflow files the pull request changes; the event is added after the prompt, so the agent reads the diff and posts a review when a new job runs with the default token.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The reason this change sits undone in so many repositories is not difficulty but reading: someone has to go through every step of every job and know what each action does with the token. The agent does that reading in its own sandbox, keeps the per-step reasoning, and lets two linters and the pull request's own CI run confirm it, so the reviewer sees a table and a green check instead of a diff they have to re-derive.

Done from the API, the same job runs across every repository the GitHub App reaches, one run each, with the same rule applied the same way, and each pull request carries the evidence that nothing it touched stopped working.

Frequently asked questions

Will the change break steps that need to write?

Only if the agent misses one, and the pull request's own workflow run is there to catch that. Each writing step gets a job-level scope, release and publish jobs included, and the description names the step behind each grant so a reviewer can check the mapping before merging.

Why put the block at the workflow level instead of on each job?

A top-level permissions: contents: read applies to every job, including the one someone adds next year, so the default inside the file becomes read-only. Job-level blocks then widen scope only where a step needs it, which is the same shape miniflux and other well-kept repositories use.

Does this cover pull requests from forks?

Forked pull requests already receive a read-only token from GitHub. The block makes same-repository branches and pushes behave the same way, and the repository setting the pull request recommends covers workflows that have no block at all.

What about actions that need secrets rather than the token?

Secrets such as a Codecov or registry token are separate from GITHUB_TOKEN and are untouched by a permissions block. The agent notes each one in its table so a reviewer sees that the step keeps working with a read-only token, as the Codecov upload in execa's workflow does.

More GitHub Actions jobs

More jobs like this: Hand off a long task

Keep reading