Skip to content

Create Release Stage


What is a release ?

GitLab’s Releases are a way to track deliverables in your project. Consider them a snapshot in time of the source, build output, and other metadata or artifacts associated with a released version of your code.

Why release ?

why should i use release ?

  1. Know exactly which release version is running in any environment.
  2. Roll back deployments of releases to production quickly, without reverting the source code.
  3. All the commits of each release are collected, and displayed at the Release page in GitLab.
  4. Write commits with specific rules, to bump minor/major changes, and increase the version accordingly.

More information about GitLab release here:

GitLab Releases

Creating a release stage

The First thing we need is a stage that will go over our COMMIT MESSAGES and promote the release version according to a set of rules.

For that we will use the open source project: go-semrel-gitlab

This project has a container image which we will use in our pipeline's release stage.

It will evaluate our commit messages, promote a version number and create a gitlab tag & release. we will then use the built in variable in GitLab: CI_COMMIT_TAG in order to tag our docker images.

In your .gitlab-ai.yml file add the release stage right after your build stage.

- build
- release

Add the following line to your other variables


Add the release stage:

stage: release
    - release next-version --allow-current
    - release changelog
    - release commit-and-tag --create-tag-pipeline
    - master
    - tags
when: manual
dependencies: []

Note about CI options

Notice except & when

    - tags
when: manual

The except declaration means this stage will not run when a GitLab tag is created.

(without it will have an endless pipeline loop)

Also since when is set to manual this means we will have to manually click on the pipeline stage button, in order for this stage to run.

The stage will be created, but will not run, it will wait for someone to click on it.

This can be changed according to your specific needs.

Tagging release

Tag our released docker image / artifacts with the release version

As mentioned above, now that CI_COMMIT_TAG will contain the release version value, We can use it for anything in our pipeline.

For our purposes, let's tag the container image we build, and push it using this tag.

For that, let's add another stage: build-release

- build
- release
- build-release

And add the build-release stage:

stage: build-release
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
    - docker build --build-arg NGINX_VER=${NGINX_VER} -t $IMAGE_TAG .
    - docker tag $IMAGE_TAG $CI_REGISTRY_IMAGE
    - docker push $IMAGE_TAG $CI_REGISTRY_IMAGE
    name: master
    - tags
dependencies: []

For this to work, we need to configure two things.

It is best to configure them at the group level, so it will effect all child projects:

  • Add GitLab CI Bot as a group/project member.

Go to Settings --> Members and add the GitLab CI Bot user with Maintener permissions

  • Set an Access Secret for the GitLab CI Bot User.

Go to Settings --> CI/CD --> Variables and make sure GL_TOKEN is set.

Commit and push

As mentioned we must meet the requirements for the release stage to work properly.

Our commit message must include specific phrases and syntax:

The go-semrel-gitlab project is based on semantic-release

So we must follow the semantic release rules for this to work

Here is an example of the release type that will be done based on a commit messages:

Commit message Release type
fix(pencil): stop graphite breaking when too much pressure applied Patch Release
feat(pencil): add 'graphiteWidth' option Minor Feature Release
perf(pencil): remove graphiteWidth option

BREAKING CHANGE: The graphiteWidth option has been removed.
The default graphite width of 10mm is always used for performance reasons.
Major Breaking Release

Commit message

Now we can commit and push to trigger the pipeline

commit & push our changes with these messages:

fix(Dockerfile): created

feat(release): added release stage

The git push to the repository will trigger the pipeline.

Once the build stage is complete, click on the created release stage and it should start.

When it's completed, go to: Project --> Releases to see the created release and the commit messages you added according to the above.

Go to Registry and find the container image with your release tag


you now have a CI Pipeline that builds and releases versions of your application with docker:

  1. We used docker to build a container image with our application code.
  2. We used GitLab Pipeline to automatically build and release container images of our application.

In the next page we will learn about Kubernetes.