Release notes API testing

If you automate the creation/publishing of release notes for your lifted package, or just want
to try adding release notes to a version via our new API, please help us test it out! We’re looking for the following feedback:

  • Clarity of API docs
  • Ease of posting/updating release notes for a version
  • Ease of creating/managing API keys

You’ll need an API key from your lifter dashboard and you can find the documentation here.

Please let us know if you run into any issues or have any questions. Thank you!


I recently had the chance to test out the new API, and it worked like a charm. :grinning:

Thank you for exposing release notes via an API so that I can automate uploading those to Tidelift (though I still need to write a tool to handle that process so I don’t have to hand-craft a bash to upload a single version :sweat_smile:).

On the API documentation, I assumed the name parameter needed to be URL encoded. My packages all begin with @hutson/, an npm scope, so the name typically needs to be URL encoded before POSTing it places. During my test, I URL encoded the name, and that seemed to work fine.

Generating a token was pretty straight forward. :+1:

I POST’d release notes for a version, 3.1.1, of my package, @hutson/generator-python-library, that does not exist (It’s not a tag on the repository or published to npm), and I received HTTP/1.1 201 Created. I’m not sure what the expected behavior should be here. :thinking:

Related to that, in the UI, I’m not sure how to access release notes for versions other than the latest. :man_shrugging: I was hoping to go back and delete the invalid version release notes. :sweat_smile:

Related to that, in the UI, I’m not sure how to access release notes for versions other than the latest. :man_shrugging: I was hoping to go back and delete the invalid version release notes.

This is a really good point, and we don’t currently have this functionality. I’ll share with the team and let you know if we have any follow up questions. Thank you for your feedback!

To help automate my release note process I finally set aside the time to write a Now-compatible (No affiliation) service that receives webhook events for tags pushed to GitLab, and forwards the tag message on to Tidelift via the Release API.

The code is available here for anyone to spin up their own webhook service to start auto-publishing release notes from GitLab to Tidelift.

It should be noted that the service uses the message property of the Tag event, which is the property containing the annotation of the tag object. At this time there is no webhook event, or event data, for the Release notes themselves. That is being tracked in gitlab-ce#57997.

It should also be noted that this only works for new releases. GitLab’s Tag event does not fire if you modify existing Release notes. They’re tracking that feature request in gitlab-ce#50205


My release notes are in ReStructured Text, so I wrote a utility to use pandoc to convert them to Markdown, then parse the Markdown section headers, and upload each section as an individual version using the Tidelift API:

It turns CHANGES.rst into Tidelift release notes

The ReST-to-Markdown is just a small part of it, if you are looking for a way to upload a Markdown file as individual versions.


I really like this approach. :+1: It allows for earlier releases to be back-filled.

1 Like

For anyone generating release notes for GitLab or GitHub using a Conventional Changelog tool (Disclosure: I’m a core maintainer in that Org), I’ve put together a Node based CLI tool called conventional-tidelift-releaser that can publish release notes to Tidelift based on your commit messages and tags. (Inspired by @nedbat’s tool for back-filling release notes from a CHANGES.rst file)

As an added benefit, I’ve added instructions on using Docker to publish your release notes using conventional-tidelift-releaser. The Docker image is unofficial, under my personal account on Docker Hub, but it’s automatically built against the latest code, and it allows you to avoid needing to setup Node in your local environment.

As a side note, the Docker image is setup to assume you follow Conventional Commits (Disclosure: I’m one of the core maintainers for that as well), but if that’s not the case, you can still use the published npm package and your own choice of preset.

1 Like

Just came across this post. I’ve posted on another one but I think this one is more appropriate.

The tool I’m busy building makes use of the file which follows the format. From that, it automatically linkifies all references, issues and PRs (also supporting user/repo#1 format).

I’m extending it to become more versatile, allowing updating of GitHub and Tidelift release notes and soon also GitLab which I still need to look into. (And maybe even Gitea/Gogs or anything else that supports release notes?)

I also wondered about this. If a release note is created before picks it up and passes it over to Tidelift, does the existing one count as “correct” or does the newly discovered one overwrite it? My vote would be to keep any release note that has been added via API.

To follow up on ReStructured Text, I tried taking some standard Python RST CHANGELOGs and running them through our existing code, and they seemed to translate over pretty well. If you want, try putting in the URL to a raw RST file in the “Read a Markdown/RST file” section of Release Notes and see if the results are good. I only tried a handful of RST CHANGELOGs and don’t know the format well, so I’d love to hear feedback on the feature and if there’s any improvements we can make for handling RSTs.