Release Automation with Gitlab CI

Hey everyone, I am back. I am having some time to write in the Carnaval Holidays.

This time I will talk about a feature in Gitlab that is not explored in many projects, mayb because it is not part of the git itself, but it has been a way to describe the tags and attach more information to the tag, as some artifacts(builds), source code, etc…

More information on releases, you can check at Github explanation.

The problem

This post is a quick one about integrating the releases automatically into your Gitlab pipeline.

Everyone knows that it is very boring every time you do a tag in your project, you have to go to releases page an add a new release with all the information about this version.

A second easier way is to include the release notes in your tag, when using the Gitlab web interface for tagging. This way the “Release” is created at the same time.

Why not automate?

For a while I’ve been studying to automate the whole pipeline in Gitlab, and let me tell you, it is a long path. When you think you are over, there is always something new that you learn.

For the releases is something you can do in pipeline too, using the Releases API.

https://docs.gitlab.com/ee/api/releases/

The link above explains “almost” everything to know about it, I’ll tell you in a while why I mentioned “almost”.

curl --header 'Content-Type: application/json' \\
--header "PRIVATE-TOKEN: <your_access_token>" \\
--data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "milestones": ["v1.0", "v1.0-rc"], "assets": { "links": [{ "name": "hoge", "url": "<https://google.com>", "filepath": "/binaries/linux-amd64", "link_type":"other" }] } }' \\
--request POST "<https://gitlab.example.com/api/v4/projects/24/releases>"

Yes, that is cool, just paste this code into my .gitlab-ci.yml?

Not really, there are a couple of things you should take into account (I learned the hard way).

1. Curl

For some reason, curl multiline commands (one line is okay, but it is hard to read) does not work very well with the parser, for this reason you may want to put a pipe in the first line, before starting the command, as discussed here in stackoverflow forums.

script:
- |
	curl --header "Content-Type: application/json" \\
...

Avoid single-quotes, put that on the list.

2. Tokens

As you see, you need some authentication to push things and you will have to generate a private token.

If you don’t know how to do it, you can check it here. The private token is a way to access the API in easy way, and it can be sometimes more secure than a password (it depends of course on how you configure and how do you handle this token).

Another way, not very clear and not very documented, is to use the Job token. Since a couple of versions ago, the Job Token can perform some actions on the pipeline, as upload container images, packages registry and create releases. To use this token, you will have to change the header a little bit, inserting the job-token as discussed here.

script:
- |
	curl --header "Content-Type: application/json" \\
	--header "JOB-TOKEN: ${CI_JOB_TOKEN}"

3. Release Data

As you may notice, now you have to put the data to perform the HTTP Post Action. This is when you really have to watch out, because not paying attention to the escape characters in JSON, it will lead you to errors. In the “data” parameter, you won’t need all the fields, only some of them are required, as described here.

--data "{\\"tag_name\\": \\"v1.0.0\\", \\"description\\": \\"### Changes:\\nSome}\\"}" \\

4. URL

The url don’t need to be typed on every project, and modifying everytime. There is some Gitlab Variables you may use to standardize the pipeline.

$CI_API_V4_URL/projects/$CI_PROJECT_ID/releases

After all of these details, if you want to insert this command into your pipeline to automate, it is easier than ever.

Example Project

For better describing this concept, I assembled an example in Gitlab. The link below goes to a Gitlab YML of this project.

https://gitlab.com/felipe_public/felipe-kb-blog/versioning-example/-/blob/master/.gitlab-ci.yml

You can navigate all other pages of this project, the releases page, commits, and see how it was done.

Wait Felipe!

“I just saw the gitlab-ci pipeline configuration, and there is much more than you just wrote.”

Yes, you are right, this pipeline also automates the Changelog generation, versioning, and the fields from the release, so I don’t ever need to manually update those again.

But, that is an idea for another post.

Until there….