GitHub Actions "HTTP 422: Reference does not exist" (create release)

Creating a release ties it to a tag at a commit. If the tag does not exist (or target_commitish points at a ref that is not present), the API rejects it with HTTP 422 Reference does not exist.

What this error means

A create-release step fails with a 422, usually because the tag was never pushed or the target commitish is wrong.

HttpError: Reference does not exist (422)
    creating release for tag v1.4.0

Common causes

Tag not pushed before release

The release references a tag that does not yet exist in the repo.

Wrong target_commitish

A target branch/SHA that is not present makes the reference invalid.

How to fix it

Create the tag first or let the action create it

1. Push the tag before creating the release, or use an action that creates the tag.
2. Set target_commitish to a SHA or branch that exists.
3. Ensure contents: write permission so the action can create the tag.

permissions:
  contents: write
steps:
  - uses: actions/checkout@v4
  - run: |
      git tag v1.4.0
      git push origin v1.4.0
  - uses: softprops/action-gh-release@v2
    with:
      tag_name: v1.4.0

How to prevent it

• Ensure the tag exists (or is created in the same job) before the release call.
• Grant contents: write for release and tag creation.

Related guides