Export Your Github and Gitlab Releases as a Changelog

January 22, 2018 • Utility Python • 4 minutes to read • Edit

The repository can be found at https://github.com/akshaybabloo/release-exporter-old.

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.

So why do we need changelog you ask? I would recommend reading this and this.

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

1. Python 3 with pip installed - I would recommend installing Miniconda if you are new to Python.
2. The account token for GitHub (see here) or GitLab (see here) depending upon what service you use.
3. 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.

BUT HOW!?

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.

1. –token - This is where you give your token, you can give it as --token=your-token or --token your-token. Make sure you change your-token with the token generated by GitHub or GitLab
2. –url - The HTTP URL of your repository.
3. –location - Your cloned local repositories absolute address. Eg: Windows - C:\Users<user>\Documents\GitHub\release-exporter or POSIX - /home//GitHub/release-exporter
4. –version - Shows the version of the Release Exporter
5. –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 :)