Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A GitHub Actions push or API call fails with permission denied to github-actions[bot]

ErrorPermission denied to github-actions[bot]

Short answer

The GITHUB_TOKEN carries only the permissions the workflow gives it. When the repository default is restricted, or the workflow lists permissions without contents: write, a push or API write is refused. Add the missing write permission to the job, or change the default workflow permissions in settings.

  • Applies to GitHub Actions, actions/checkout v4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find which permissions the workflow sets, then compare with what the failing step does: a push needs contents: write.

    grep -n -A4 "permissions:" .github/workflows/*.yml
  2. 2Match what you see, then jump to its fix

    1. 1The push or write is refused, and the workflow has no permissions: key.The repository default token is restrictedFix
    2. 2The workflow has a permissions: block, for example pull-requests: write, but the step that fails needs contents.A permissions: block lists some scopes, so the others became noneFix
    3. 3The same workflow works on branches of the repository but fails on pull requests from forks.The run comes from a forked pull requestFix
    4. 4The token has the right permissions but the action still fails, for example on another repository.The job needs more than GITHUB_TOKEN can haveFix

What does the error look like?

  • Permission denied to github-actions[bot]

Cause 1 of 4

The repository default token is restricted

1Check

Under Settings, Actions, General, Workflow permissions can be set to a restricted option that grants read access to contents and packages only.

# Settings > Actions > General > Workflow permissions

2Fix

Grant the permission in the workflow itself. This is safer than switching the whole repository to the permissive option.

jobs:
  update:
    runs-on: ubuntu-latest
    permissions:
      contents: write

3Verify

Re-run the job; the push succeeds.

gh run list --limit 3

Confirmed by docs.github.com

Did this fix it?

Cause 2 of 4

A permissions: block lists some scopes, so the others became none

1Check

When any permission is set explicitly, every permission you did not list is set to none.

grep -n -B1 -A6 "permissions:" .github/workflows/*.yml

2Fix

List every scope the job uses, not only the new one.

permissions:
  contents: write
  pull-requests: write

3Verify

Re-run; both the push and the pull request call work.

gh run watch --exit-status

Confirmed by docs.github.com

Did this fix it?

Cause 3 of 4

The run comes from a forked pull request

1Check

Workflows for forked pull requests generally cannot receive write access unless an administrator enables the relevant setting.

gh run list --limit 10

2Fix

Do not write back from the fork's pull request run. Move the write step to a workflow that runs on the base repository after merge, or use a GitHub App or a token stored as a secret for that purpose.

on:
  push:
    branches: [main]

3Verify

The write step runs after merge on main and succeeds.

gh run list --limit 3

Confirmed by docs.github.com

Did this fix it?

Cause 4 of 4

The job needs more than GITHUB_TOKEN can have

1Check

The token's permissions are limited to the repository that contains the workflow.

grep -n "GITHUB_TOKEN" .github/workflows/*.yml

2Fix

Create a GitHub App and use its installation access token, or store a personal access token as a repository secret and use it for that step.

- uses: actions/checkout@v4
  with:
    repository: OWNER/OTHER-REPO
    token: ${{ secrets.OTHER_REPO_TOKEN }}

3Verify

The step can now read or write the other repository.

gh run watch --exit-status

Confirmed by docs.github.com

Did this fix it?

How do I stop it coming back?

  • Set permissions: at the job level with the least access each job needs.
  • Use the restricted default for the repository and grant write per job.
  • Write back from workflows that run on your own branches, not on fork pull requests.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

docker pull or push to ghcr.io fails with 'denied'

Error response from daemon: denied

ghcr.io refuses a pull or push when Docker is not logged in, when the token lacks the package scope, or when the workflow's GITHUB_TOKEN has no packages permission or no access to that package.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.