gh release delete: Remove a Release in CI

By Daniel Zoghalchali·Latchkey

gh release delete deletes a release by tag, with an option to also remove the underlying git tag.

Rollback and re-publish jobs delete a bad release before re-creating it; --cleanup-tag avoids leaving a dangling tag behind.

What it does

gh release delete removes the release object for a tag. By default the git tag remains; --cleanup-tag deletes the tag too. In scripts you must pass --yes to skip the confirmation prompt.

Common usage

gh release delete v1.2.0 --yes
gh release delete v1.2.0 --cleanup-tag --yes
gh release delete v1.2.0 -R owner/repo --yes

Flags

In CI

Set GH_TOKEN and permissions: { contents: write }. Without --yes the command tries to prompt and fails on a non-interactive runner. Deleting the release does not delete the tag unless you add --cleanup-tag.

Common errors in CI

"GraphQL: Resource not accessible by integration" or "HTTP 403" means the token lacks contents: write. "release not found" means the tag has no release attached. Without --yes you may see the command hang or exit because no terminal is available to confirm.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

Related guides

References

• GitHub Actions documentation