Debug semantic release not detecting older tags

semantic-release logo

Whether you’re a public package maintainer or as part of best practices, you’re using semantic-release to automate version management and package publishing. Sometimes you prefer to revert a release due to a mistake. You might use revert a Pull Request or rewrite your git history by forcing your changes.

Semantic-Releases uses git tags and git notes to automate versioning. Any action that breaks dependencies between your tags might prevent semantics-release from detecting history as you anticipate.

Here I will walk through how you can debug your environment to recover from that situation.

Double-check your tags

To find some clues, you can first check if your previous tags are already present. To make this, use git tag --list to list tags in your current repository.

List tags in your current repository [Image by author]

If you’re expecting version v1.2.1, you should be able to find v1.2.1 in the list.

Are you using a CI? In this case, check the documentation of your CI system to include tags when cloning. Some CI platforms use partial or shallow clones to reduce clone sizes to boost build time or skip fetching tags. Let’s quickly review clone types.

Clone types

• Full clones: Clones latest commit and all reachable objects that are blobs (files), trees (directories), and commits.

$ git clone <repository>

• Blobless clones: Clones all commits and trees reachable by the latest commit while fetching blobs as needed

$ git clone --filter=blob:none <repository>

• Treeless clones: Clones all commits reachable by the latest commit while fetching blobs and trees as needed.

$ git clone --filter=tree:0 <repository>

• Shallow clone: Truncates commit history specified by --depth the argument.

$ git clone --depth=1 <repository>

For instance, if you’re using Drone CI be sure to specify tags: true and not to use shallow clones.

clone:
  git:
    image: plugins/git
    settings:
      tags: true

Verify your git history

While rewriting your history, your tags might not have become disjoint from your commits. To find which tags are reachable by the current history of your branch, simply use git tag --merged. Did you find your anticipated tag in the list? If not, you need to join them back together. One option is to merge the tag back to your current branch git merge <tag>. Remember to fetch your update tags before executing git fetch --tags <remote>, as there’s a chance that your local tags have been quite different than your remote git repository. Then you should be able to see the command again.

List tags reachable by current branch [Image by author]

Verify your git notes

Were you able to fix it? If not, we got you. semantic-release also uses git notes to track version history. The first step you need to do is to delete the tag that has been lost from the history

To delete the tag from the remote:

$ git push <remote name> -d <tag name>

Then you can delete the tag locally:

$ git tag -d <tag name>

The second step is to recreate the tag and associate it with the new commit hash

$ git tag <tag name> <commit hash>

Third, you need also to recreate the git note. For this run, the following.

$ git notes --ref semantic-release add -f -m '{"channels":["your channel"]}' <tag name>

For channel, take a look at your semantic release channel name defined in your configuration. In case this release is also published in the default channel, add null as the first channel in the channels list as follows:

$ git notes --ref semantic-release add -f -m '{"channels":[null, "your channel"]}' <tag name>

Conclusion

semantic-release eases your workflow and creates a maintainable environment for you to develop your software. The only requirement is to maintain a clean git repository. This article discussed debugging your git repository to recover from the situation where semantic-release doesn’t detect old tags.

I’m going to write more articles in CS; thus, if you find it interesting and helpful, please follow me on medium. Also, please feel free to contact me directly via LinkedIn.