GitLab Release Stage, 27 Jul 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Create releases from .gitlab-ci.yml Part 2

Description

Introduced in GitLab 13.2.

You can now create releases using the release keyword as as step in your .gitlab-ci.yml file.

- CI reference https://docs.gitlab.com/ee/ci/yaml/#release
- Sample project https://gitlab.com/jaime/hello
- Release node issue https://gitlab.com/gitlab-org/gitlab/-/issues/199250
- Release generation epic https://gitlab.com/groups/gitlab-org/-/epics/2510
- Release CLI https://gitlab.com/gitlab-org/release-cli
- Add first-class semantic versioning to Releases https://gitlab.com/gitlab-org/gitlab/-/issues/213838

A

Hi everyone, my name, is jaime martinez and I'm a backend engineer in the release management team here at gitlab uh today, I'm gonna show you how you can create releases from your gitlab ci yaml file.

A

As you can see in the in the blog post for 13.2, we introduced this release, keyword that you can use in the in the yaml file so that the gitlab runner can actually parse it, and you can create a release much more easily. Now you can find the documentation in the ci jamal reference page in the docs, as you can see, introduce and gitlab 13.2.

A

The release keyword indicates the job that you can create a release in it and to optionally include a few parameters.

A

So the methods uh that are supported are adding a tag within which uh the release will be created from, and you can use the name for your release, a description, a ref or a commit reference to create the the release from. If you don't have a tag you can use milestones if you have defined them in your project and you can use the timestamp to say when this release was actually available from.

A

um So I can show you a little bit.

A

We have a couple of examples in here.

A

There are two possible ways that you can create a release as of today, one is by generating at a git tag and by the time you push it to your repo, then the the release job can pick it up and create a release from that tag. So, as you can see here, we have a release job and we have the steps defined, and the one important thing to note is the rules. We need to do it when there is a commit tag and so that the job will only be picked up.

A

If you push a tag um and as you can see, we can just add the release node into this job and say: okay, I want my release to be named release with the value of the tag. We can add a description and we can have the tag name. We can have a ref if we need to and we can add milestones and release stand.

A

One thing to note here is, as you can see, we have an extra descriptions uh environment variable defined here and you can see in the docs. It says you need to define it somewhere else in the pipeline, so I'm going to show you that in just a moment, okay, so on the left side on this side of the screen, I have a sample project that you can find I'll reference in the in the video description.

A

I'm going to show you how you can create a release from a tag and how you can create an auto release I'll get into that in just a moment. So I have a couple of files. One is the release from tag which is just here, and this is my job release from tag the image we are using. uh Docker executor so yeah.

A

It's important to note that you need a gitlab runner with a docker, execute executor and the image we're using is the release eli that it was mentioned in a couple of videos ago and won't go into details but I'll I'll link it here in the video description and I'll skip this. For now, uh I'm saying, as a rule just run it when there's a commit tag, um and we just we at the moment. We require a script, because uh the runner always needs a script.

A

uh There's some issues around not needing a script when there's a release and we'll get into that a bit later. But basically this is a release. We are saying same as the example. We're gonna create a release from this tag. We're gonna have this extra description and we're gonna use uh this tag name, the reference can be a commission, it can be a tag itself or it can actually be a branch name as well.

A

In this example, I'm just going to use a commit tag and I'm adding this to milestones and I'm also saying that this release was actually available from the 27th of july 2020 at 4, 10 p.m, utc plus 11, which is sydney time.

A

So I am going to show you my sample project. You can go to github.com, jaime hello. All of this is here available for you to take a look.

A

As I mentioned, there's the important thing is the: if you want to create, if you want to use milestones in your release, they need to exist, otherwise the job will fail. So that's one important thing to note:.

A

So yeah, what I'm gonna do is I have this uh shell on the side and what we're gonna do is gonna, create a tag. I'll show you. This is what is on my default branch. I actually have this to say: release from tech. So if I create a tag, I get tagged and I push it. This should pick up the new release so say: I'm just gonna do an annotated tag and say testing, and let's just say this is gonna- be 1.2.0.

A

Okay, let's just verify that the tag is there.

A

Yep, so the tag is here: testing be 1.0, 1.2.0 and just gonna. Do it push.

A

A

Okay, so if we go to the pipelines, we should be able to see this. This job picked up. That's right, so we're going to say, tag v1.2.0,.

A

And while this is running, I'm going to show you what this prepare step is doing, and this is a release step. So, uh if you remember this in the documentation, we say that any environment variables that you need to define before the job need to run somewhere else in the pipeline.

A

So in this case I'm going to create a generate description, job uh it's at a previous stage, yeah, and I'm also only running it when there's a commit tag and in my script step, what I'm doing is I'm gonna create this extra description variable and at the moment, what I'm doing is just pushing it piping it into this description.m file and we're going to take advantage of the artifacts reports.m.

A

So this is this feature that allows you to export a name environment file, dot, m emv, and this can actually be used later in your other steps or in your other jobs. So, for example, here in the release job, I'm saying, okay, I need this job. This generate description job to to wrong. First, and I'm saying I need the artifacts right, so what this is gonna, do this dot m is going to source this file, so this environment variable is going to be available later in the steps.

A

So, okay, so I'll click on this job and as you can see, this is running the steps and the script running release from commit tag. So here it is running release from v10 1.2.0 um and uh basically, what this release uh job is doing is generate.

A

All of this uh all of these uh parameters to pass into a release cli and the release. Cli is this docker image that we define in this step and with those uh parameters, then the release click and create the the release, so everything job succeeded. So if I go into the releases page.

A

I should be able to see this release v. 1.2.0.

A

And here's a description for it, you can see created using the release cli and with the extra description generated some extra description first, so there you go. That's one and the second step I'm gonna show is: how can you sort of automate this release step?

A

uh It's worth, noting that we're doing some some work and investigation on how we can uh do some uh semantic versioning, and how can you leverage that to create releases automatically, uh but that's not uh implemented yet is, but there we have some issues that um that you can find and to keep track of this, this kind of work.

A

So I'm just gonna reference, this other pipeline, auto release and this one the rules are a bit different and, as you can see, I have uh generate tag, um prepare step, prepare job uh and what I'm saying is don't run when there's a tag only run it. When I push any changes to the default branch uh and, for example, in in this case I'm gonna, say: okay grab the tag from whatever my version file has so right. Now uh the version file is this.

A

So, let's, let's just do something a bit different, let's say for some reason, we're already in version.

A

1.5.0 and I'm gonna say: okay export this version into tag.env we're doing the same trick of using the artifacts reports um and then the release. Job itself is uh it's here: there's not a lot of not a lot has changed. Only the rules and I'm gonna say: okay, release from the environment, variable tag which was exported here in this file and we're gonna say created using the release. Cli extra description. Now, I'm not defining anything here. So this this will be empty, but the tag.

A

Okay, so now we're gonna say, create the tag.

A

The tag name from this environment variable and the important thing to know this tag name doesn't exist right, so this git tag doesn't exist yet so the releases api needs to know where to create the the release from- and in this case I'm saying, okay just use the command shot for for this release, but, like I mentioned before, it can be a branch name or it can be another tag like in the other example, or it can be the commission and then in this for this release.

A

Let's just say it was just for one of the milestones. Not just both milestones is an array, so you can. You can specify as many as you want and and I'm skipping the release ad, because I just wanted to. I just want to generate a release when this, when this tag is created with this current timestamp.

A

um Okay. So let's go ahead and commit.

A

This create release.

A

A

All right, so let's go and look at the pipeline.

A

Okay, so it's running right now and we're saying uh create a release from the full branch. So if you can see here, the prepared stage has the generate tag file in here. Sorry, joe and all it's going to do is read this version file that we committed now, like I said you can use some other tools to generate this tag, some semantic versioning, for example, or if you use a package.json file to give the version for example, then you can use that so this this script is up to you to.

A

However, you want to generate this tag and if you want to do it automatically in the process or not okay, so this this job is done. So the m file should be ready. So we go back to the pipeline and say: okay release.

A

Okay, so this job is called auto release master. So this should be the is the name of the default branch in my project and, as you can see, and we're saying, okay, release, 1.5.0 and it's doing the same thing. It's generating these steps for the release. Cli and it's saying: okay created a release and if you look at the timestamp it's july, 27 2020 at 702 utc and we can see all available releases or I can just click on the releases. Tab.

A

And here it is so the latest release is 1.5.0 uh yep. Oh, I missed the v at the top at the front because I only said to cat the version, but that that's fine um whoops, I click on it, so you can see release 1.5.0. It matches only one milestone that we just pointed here created using the release cli and, like I said, the extra description is empty, so there's nothing else and created one minute ago. So that's because I didn't specify the release date so yeah there you go.

A

There's uh there's two examples: um how you can run. How can you create releases from the yaml file, uh the the important thing uh to notice that combining these two examples? uh You it's a bit dangerous?

A

That's why we say these options cannot be used together and by dangerous I mean we can go into a loop of creating or creating releases or failing releases.

A

So, for example, I said I want to create a release from a tag and I want to create an auto release when I push to my default branch, so what's happening behind the scenes. Is this, this git tag is going to be created here right, so the first job is not going to be picked up when we say release when when we push to the master branch, this release from tag job is not going to be picked up.

A

This one will- and this will generate this tag all right and what's going to happen is once this is done because of the nature of the api. A git tag is going to be pushed to the ripple, and then the pipeline is going to pick it up to say: oh there's, a tag, I need to create a release from this tag, and, what's going to happen, is.

A

Because this tag already exists and this release already exists, your job is going to fail and that's one example when it fails, but it can potentially lead to a loop where maybe this creates a an automatic tag, somehow with a timestamp for example, and then the the time is going to be different, so the release may not be created. So uh you know this is a bit um dangerous. So, just just as a note here keep an eye on this. uh How how you can avoid having these issues?

A

Now we have an issue for addressing this in the future. If you think it's valuable, please let us know and yeah we'll we'll go ahead and try to figure something out for this, um but yeah. um Let's just say: let's try, let's see what happens when I enable.

A

A

Okay- let's see so, if both are enabled, they should pick that pick up the oops. I forgot to update the tag. This is gonna fail. Sorry, the.

A

The version file I forgot to update the version file, so this job is gonna fail. So, okay, let's go ahead and change it. Let's just say it's a minor fix.

A

Release, let's include the v this time.

A

A

Yeah, so the the first auto release failed because the the version already existed uh so yeah like you, can see the api replied and said: hey, uh there's a conflict. Your release already exists, so don't don't create another release from the same one. Okay. So this one okay, so using the correct version is running.

A

It's gonna generate the tag from the file first. This takes a little bit.

A

Yep, so this job is there: it's done creating the release.

A

Okay yep, so we created the 1.5.1 with the correct tag this time and if we go back to the pipelines.

A

As you can see, there's another job that was picked up because the new tag was pushed to the repo so yeah this this job is gonna pass. This is fine, but when we go into the release from tag, we're gonna have an issue. We're gonna encounter the same issue, because the release already exists and just to show you so release. 1.5.1 is already here, and this is the awesome releases page. The team has been working on uh recently. You can go ahead and edit releases you can do other stuff, but yeah.

A

I'm not gonna, go too much into detail here.

A

Okay, so this job, okay, yep, so basically uh failed for the same reason, because the release already exists all right, so uh yeah, that's pretty much it thanks. Thanks for watching and please reach out, uh you can find me on gitlab.com at jaime j-a-I-m-e, uh so yeah. Thank you.