GitHub Actions JamesIves/github-pages-deploy-action "permission denied"

JamesIves/github-pages-deploy-action publishes by pushing built files to a branch (gh-pages by default). That push needs contents: write on the workflow token, or a deploy token; without it the push is denied.

What this error means

A github-pages-deploy-action step fails pushing to the deploy branch with a 403 or permission-denied error.

remote: Permission to acme/site.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/acme/site.git/': The requested URL returned error: 403
Error: The deploy step encountered an error: The process '/usr/bin/git' failed with exit code 128

Common causes

Read-only workflow token

Without permissions: contents: write the bot cannot push to the deploy branch.

Protected deploy branch

Branch protection on gh-pages can block the automated push.

How to fix it

Grant write access for the push

1. Add permissions: contents: write to the job.
2. Or supply a deploy token/ssh-key with push rights to the branch.
3. Relax branch protection on the deploy branch for the bot if needed.

permissions:
  contents: write
steps:
  - uses: JamesIves/github-pages-deploy-action@v4
    with:
      branch: gh-pages
      folder: dist

How to prevent it

• Set contents: write explicitly on Pages deploy jobs.
• Exempt the deploy bot from branch protection on the publish branch.

Related guides