Export Your Github and Gitlab Releases as a Changelog
The repository can be found at https://github.com/akshaybabloo/release-exporter.
At the time of writing this blog post, I have 55 repositories on my GitHub account, and more than half of them are active. None of the repositories has a changelog in it, but I have made sure that I have written the release notes at the time of releasing the package/software.
Now the problem is that I do not want to waste time by copying individual release notes to a markdown file for all the repositories I have. Enter Release Exporter. Release exporter makes it easy for you to generate a changelog in the form of markdown or a JSON file and it supports GitHub and GitLab releases. I tried my best to develop the application that follows the format of keep a changelog v1 and Markdown lint.
How to use it then?
It is a command line application, that means no coding required (hooray!!!), so you need three things
- Python 3 with pip installed - I would recommend installing Miniconda if you are new to Python.
- The account token for GitHub (see here) or GitLab (see here) depending upon what service you use.
- The will to do this.
To install Release Exporter, open your favourite command line - terminal/command prompt and type in
> pip install release-exporter
Once installed, there are three ways to use it. The simplest way is to change your directory to your local repository on the terminal/command prompt (but make sure your repository is cloned from GitHub or GitLab) type in the magic word with your token as
> rex --token your-token markdown
The markdown creates a CHANGELOG.md file in the same folder.
If you have noticed, you have not given the URL for your repository so how did it generate the log file then? All right, here is the secret. When you clone your repository from GitHub or GitLab or if you create one with remote URL, a folder .git/ is created in your project folder. The file the application is looking for is config, it is a configuration file that follows INI standards, and Python can parse such files. Release exporter looks for a specific section [remote “origin”] which has url and fetch keys, the url key is what Release exporter is interested in, this is the URL of your remote (GitHub or GitLab) repository. That is it, using this URL and your user token, the CLI can generate the logs for you.
A BIT MORE ADVANCED FEATURES
Few advanced features could help you in case the easy one does not work. To get help, type in
> rex --help Usage: rex.py [OPTIONS] COMMAND [ARGS]... Options: --token TEXT Token number if its a private repository. --url TEXT URL of your repository. This is optional if your current directory has .git folder with remote url. --location TEXT Local location of your repository. --version --help Show this message and exit. Commands: json Creates JSON file. markdown Creates markdown file.
- –token - This is where you give your token, you can give it as
--token your-token. Make sure you change
your-tokenwith the token generated by GitHub or GitLab
- –url - The HTTP URL of your repository.
- –location - Your cloned local repositories absolute address. Eg: Windows - C:\Users<user>\Documents\GitHub\release-exporter or POSIX - /home//GitHub/release-exporter
- –version - Shows the version of the Release Exporter
- –help - Shows helpful information about the CLI application.
If you change the markdown with json, a CHANGELOG.json file is created see here for example.
WHY USE THE TOKEN?
GitHub v4 API (latest version) uses GraphQL, which is a query language. It being a query language, the request needs to be done using POST so to limit the access to a certain area of your repository, the token is required and also if your repository is private, the token makes your private repository visible to the release exporter.
However, GitLab does not yet use the GraphQL (it is still under development, I will update the API once they are released for production), so it uses GET request. To be on the safe side, your token is needed and also if your repository is private this removes the accessibility problem.
Happy logging :)