JamesIves/github-pages-deploy-action "fatal: couldn't find remote ref"

The deploy action fetches the target branch (often gh-pages) before pushing built files. On the first deploy that branch does not exist, so the fetch of its ref fails.

What this error means

The pages-deploy step fails with "fatal: couldn't find remote ref refs/heads/gh-pages".

github-actions

fatal: couldn't find remote ref refs/heads/gh-pages
##[error]The deploy step encountered an error: The process failed with exit code 128

Common causes

Target branch missing on first deploy

The branch named in the action input has not been created yet.

Wrong branch name

A typo in the branch input points at a ref that does not exist.

Missing contents: write

Without write permission the action cannot create the branch.

How to fix it

Grant write and let the action create the branch

Add contents: write to the workflow permissions.
Confirm the branch input matches your intended deploy branch.
Re-run; the action creates the branch on first deploy.

.github/workflows/pages.yml

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

How to prevent it

Grant contents: write so the action can create the deploy branch.
Keep the branch input consistent across runs.