Two dates, two different jobs
If you create v2.3.0 on Friday and write its release page on Monday, GitHub can show a tag date and a different release date. That gap is useful: one marks a commit in the project’s history, while the other signals that you are presenting a version to users.
A Git tag is a name attached to a particular point in repository history. It can help you return to a commit, identify a build, or record a milestone. A GitHub release is built around a tag, but adds a page for describing and distributing that version.
Think of the tag as the address and the release as the delivery note. The address is useful to you and your tools even when nobody needs an announcement. The delivery note is useful when someone outside the team needs to know what changed, whether to upgrade, or where to get the files.
That distinction is why “one tag per version” does not have to mean “one public release per tag.” The right choice depends on whether a version needs a user-facing handoff.
Start with the audience, not the version number
A version label such as v2.3.0 looks official, but the label alone does not tell you whether to publish a release. Ask who needs to act on it. If the answer is only “our CI job needs a stable name for this commit,” a tag may do the job. If the answer includes a user, administrator, package maintainer, or downstream developer, a release page may save them real investigation.
For example, a tag on a commit used to test a nightly deployment can be an internal coordination point. A version of a command-line tool that users install is different: they may need to know which fixes landed, whether an upgrade changes behavior, and which artifact to download.
The practical test is not whether the version is numbered. It is whether a person who did not watch the commits needs a clear point of reference. If they do, a release can turn a repository event into a useful update.
Use this decision rule for each version
Before creating a release page, ask whether it adds information or access beyond the tag. Use a release when at least one of these is true:
- Users need a concise summary of changes since the previous version.
- People need a stable page to find or download release artifacts.
- You want users to be able to follow new releases without following every repository update.
- The version is a supported or recommended point of use that people may need to cite or share.
If none applies, and the tag is only for build automation, a deployment marker, or internal coordination, keep it as a tag. A public page with no useful notes or files can create the appearance of a user-facing announcement without answering a user’s questions.
This rule also handles mixed projects: publish releases for user-facing versions, but keep tags for internal checkpoints. The artifact should match the audience, not a blanket policy that every tag gets a page.
What a release page adds—and what it costs
A GitHub release gives a version a public landing page with a title and description, and it can include downloadable files. That page can gather the information a user otherwise has to reconstruct from commits, pull requests, or a separate changelog. GitHub also lets people receive notifications about new releases without receiving notifications about other repository updates.
Those features have a maintenance cost. Someone must decide what the notes say, verify that the release points to the intended tag, and keep any linked downloads or instructions accurate. If you publish ten internal tags a day, turning all ten into release pages may add ten empty or repetitive announcements without helping anyone make a decision.
There is also a timing detail worth preserving: the tag and release can be created at different times, so their dates need not match. That is not inherently a problem. It does mean that a team should avoid treating a tag’s timestamp as the moment users were told a version was ready.
Work through a real version from commit to user
Suppose a small team maintains a command-line tool. Its CI pipeline tags a commit after a successful build so the team can identify the tested source. That tag has a clear internal purpose, but it does not yet tell a user what changed or whether to download anything.
When the team decides the version is ready for users, it can create a GitHub release for that tag. The notes might summarize the two user-visible changes since the last version, call out an upgrade consideration if there is one, and link to the project’s installation instructions or release files. The page now answers questions that the bare tag cannot.
If the build fails before publication, the tag can still mark the commit that CI tested; there is no need to present it as a finished user version. If the team instead ships the same commit immediately and users need to locate it, the release page adds value. The decision follows the handoff, not merely the existence of the label.
Write notes that help someone decide
Release notes do not need to repeat every commit message. Their job is to describe the difference between this version and the last one in terms that matter to the person using the project. A useful short note might say, “Adds export to CSV and fixes authentication when the token contains a plus sign.” That is more actionable than a list of internal commit subjects such as “cleanup,” “tests,” and “fix.”
For a version with no meaningful user-facing change, do not manufacture a story. If the release page is still useful as the stable place to get the version, say briefly that it contains maintenance changes and point to the changelog for detail. If neither the page nor the notes help users, keep the tag and avoid a hollow announcement.
Generated notes can help collect merged work, but they still need review. Check that the comparison is against the intended previous version and that the resulting summary does not imply a change that was not shipped. A polished page with the wrong comparison is worse than concise, accurate notes.
Keep the tag and release tied to the same commit
A release is based on a Git tag, so confirm which commit that tag names before publishing. This matters when you create a tag from an older commit, when branches have diverged, or when a release is prepared after the code was tagged. A correctly written description cannot fix a page that points users at the wrong source revision.
For a local annotated tag, a basic flow looks like this:
git tag -a v2.3.0 -m "Version 2.3.0"
git push origin v2.3.0
gh release create v2.3.0 --notes-from-tag
GitHub CLI can use the annotated tag’s message as release notes with --notes-from-tag; if the tag is not annotated, it uses the commit message instead. That fallback may be convenient, but a commit message is not automatically a good user-facing summary. Review the text and confirm the target before publishing.
If you create the release through GitHub’s interface, check the selected tag and target commit there as well. The operational question is simple: does the page describe the exact source users will get?
Make the policy explicit for mixed-purpose repositories
Repositories often contain more than one kind of tag. A team may tag a stable application version, mark a test build, and use another tag for a deployment checkpoint. Calling all of them “releases” blurs their purposes. A short team policy can prevent that confusion: publish a GitHub release when a version is intended for users; use a tag alone when it is only a source-history or automation marker.
That policy should also define who owns the release notes and what they must contain. For a small project, the maintainer who cuts the version may be the right owner. For a project with several contributors, a reviewer can check the tag target and user-facing summary before publication.
Consistency matters more than making every page look identical. Users should be able to tell which tags represent supported versions and where to find the information for those versions. If internal and user-facing tags are mixed, use clear naming and documentation rather than asking readers to infer intent from a tag alone.
What to do this week
Look at the last five tags in your repository and write down what each one was for: a user-ready version, a CI checkpoint, a deployment marker, or something else. Then check whether the people who needed each version had a useful place to find its changes or files.
For each user-ready version, confirm that its release page points to the intended tag and includes a short summary of what changed. For internal-only tags, keep the tag if it serves a workflow, but do not create a public release page just to make the release list look complete.
Finally, add one sentence to your release checklist: “Publish a GitHub release when users need notes, files, or a stable announcement; otherwise, tag the commit.” That turns the tag-versus-release decision into a repeatable handoff instead of a rule that every version must follow.