Configure GitHub tags to organize repositories

  • 3 minutes

Tags in GitHub repositories are markers that denote specific points in the history of a project, such as designated commits or release versions. By assigning tags to commits or releases, developers can create a structured timeline of their project's development, making it easier to track and reference important software lifecycle milestones.

Planning

To take full advantage of tags in GitHub repositories to organize your codebase, making it easier to navigate and understand, consider the following considerations when planning for their implementation.

Release versions

Tag specific commits or releases as versions. Follow the semantic versioning notation, broadly accepted as de facto standard for labeling software releases. It is common to prefix your version names with the letter v (e.g. v1.0.0 or v2.3.4). If the tag isn’t meant for production use, add a pre-release version after the version name (e.g. v0.2.0-alpha or v5.9-beta.3). This helps users and collaborators easily distinguish between stable releases and features that are still in the testing phase.

Feature releases

Tag commits or merges that introduce new features or significant changes to the codebase. Use descriptive tags like "feature/new-login-page" or "feature/payment-integration" to highlight specific feature releases. These tags provide a clear history of feature additions and help track the progress of individual features over time.

Bug fixes

Tag commits or merges that address bug fixes or issues reported by users or collaborators. Use tags like bugfix/issue123" or "fix/critical-bug" to denote bug fix releases. Bug fix tags make it easy to identify commits that resolve specific issues and ensure that fixes are applied consistently across different versions of the project.

Maintenance releases

Tag commits or merges that involve maintenance tasks such as code refactoring, documentation updates, or dependency upgrades. Use tags like "maintenance/code-refactor" or "update/documentation" to mark maintenance releases. Maintenance release tags help track changes related to code maintenance and ensure that necessary updates are documented and applied correctly.

Custom tags

Create custom tags to categorize commits or releases based on your organization's specific needs or workflows. For example, you can create tags like "documentation", "performance", or "security" to classify commits according to their focus areas. Custom tags provide additional flexibility in organizing and structuring your codebase according to your project's requirements.

Implementing

To assign a tag to a Git repository in GitHub, you can follow these steps:

  1. Identify the specific commit or release that you want to tag in your repository. You can find the commit hash or release version in the commit history or releases section of your repository. If you're tagging a commit, copy the commit hash associated with the commit you want to tag. If you're tagging a release, copy the release version (e.g., "v1.0.0").
  2. In a local clone of the repository, use the git tag command line to create a tag. The basic syntax for creating a tag is git tag <tag_name> <commit_hash>. Replace <tag_name> with the name of your tag and <commit_hash> with the commit hash or release version you copied earlier.
  3. Push the tag to GitHub by running the command git push origin <tag_name>. Replace <tag_name> with the name of the tag you created.
  4. After pushing the tag, you can verify that it has been successfully created by navigating to the Releases\Tags page of your repository on GitHub.

Note that you can create tag protection rules for your repository to prevent contributors from creating or deleting tags. However, keep in mind that, as of March 2024, tag protection rules are in beta and subject to change.