GoReleaser "is not a valid semver tag" in CI

By Kaveh Alemi·Latchkey

GoReleaser requires the release tag to be valid semver, normally vX.Y.Z. A tag like release-1 or 1.0 fails validation before any build starts.

What this error means

GoReleaser stops with "'<tag>' is not a valid semver tag" and does not build. The tag exists but is not in vMAJOR.MINOR.PATCH form.

⨯ release failed after 0s
  error=tag "release-2024-06" is not a valid semver tag

Common causes

The tag is not semantic versioning

Tags such as 1.0, v1, or release-2024-06 lack the full MAJOR.MINOR.PATCH triple GoReleaser validates against.

A prerelease suffix is malformed

A suffix that is not a valid semver prerelease (for example v1.2.3_beta) also fails the check.

How to fix it

Retag with a valid semver tag

1. Delete the malformed tag locally and on the remote.
2. Create a vMAJOR.MINOR.PATCH tag such as v1.2.3.
3. Push the new tag to trigger the release.

git tag -d release-2024-06
git push origin :refs/tags/release-2024-06
git tag v1.2.3
git push origin v1.2.3

Use a valid prerelease format

For prereleases, use a dot-separated semver suffix like -rc.1 or -beta.2.

git tag v1.2.3-rc.1
git push origin v1.2.3-rc.1

How to prevent it

• Standardize tags on vX.Y.Z across the project.
• Validate tag format in a pre-release check or a tag protection rule.
• Use -rc.N / -beta.N for prereleases so semver stays valid.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation