gilde-ci-cd/documentation/chapters/pipelines/update-version.adoc

:sourcedir: ../../../pipelines

ifndef::imagesdir[]
:imagesdir: ../../images
endif::[]

[#_pipeline_release]
= Release Version Pipeline


This pipeline is a drop-in pipeline meant to make releases of your software as easy as possible.
The pipeline is split into a main and a child pipeline.

The main pipeline provides infrastructure to create Gitlab-releases and the triggers for the child pipeline.

The child pipeline is meant to create a new git tag with an increased Version.
You can easily extend the child pipeline to publish Artefacts.
Although this is possible we recommend using tagged pipelines.

== Overview diagram

[mermaid]
....
graph TB
.gitlab-ci.yml-->release-template.gitlab-ci.yml
release-template.gitlab-ci.yml-- release-->release.gitlab-ci.yml
release.gitlab-ci.yml-->pipelines/update-version-pipeline.gitlab-ci.yml
release.gitlab-ci.yml-->container-publish.gitlab-ci.yml
.gitlab-ci.yml--test-->container-scan.gitlab-ci.yml

subgraph project
.gitlab-ci.yml-->release.gitlab-ci.yml

end

subgraph Gitlab-CI-templates
release-template.gitlab-ci.yml

pipelines/update-version-pipeline.gitlab-ci.yml-->push-tag-and-version-template.gitlab-ci.yml
pipelines/update-version-pipeline.gitlab-ci.yml-->set-version-template.gitlab-ci.yml
set-version-template.gitlab-ci.yml-->exxcellent-increase-version-tool/increase-version

container-publish.gitlab-ci.yml-->.publish-image-kaniko

container-scan.gitlab-ci.yml
end

....

== Setup

This pipeline should be included as a child-pipeline in your gitlab-ci pipeline.
You then can add an individual release job for each kind of version bump.

NOTE: You only need the variable `PARENT_PIPELINE_ID` , if you use an https://docs.gitlab.com/ee/ci/yaml/README.html#artifact-downloads-to-child-pipelines[artifact of you parent-pipeline in your child pipeline]

In your gitlab-ci.yml include the following

.gitlab-ci.yml
[source, yaml]
----
stages:
  - release

include:
  - project: 'gilden/ci/gitlab-ci-templates'
    ref: 'master'
    file:
    - 'templates/releasing/release.gitlab-ci.yml'

a.major-release:
  #Pressent in all Pipelines
  extends: .release-common
  variables:
    BUMP_VERSION: "major"

b.minor-release:
  #Pressent only on Default Branch
  extends: .release-default
  variables:
    BUMP_VERSION: "minor"

c.patch-release:
  #Pressent only on Release Branches
  extends: .release-release-branch
  variables:
    BUMP_VERSION: "patch"

d.prerelease-release:
  #Pressent only on Release Branches
  extends: .release-release-branch
  variables:
    BUMP_VERSION: "prerelease"

e.build-release:
  #Pressent only on Release Branches
  extends: .release-release-branch
  variables:
    BUMP_VERSION: "build"

----

Create a child-pipeline file called `release.gitlab-ci.yml` and include the following:

.release.gitlab-ci.yml
[source, yaml]
----
stages:
  - set-version
  - push-tag-and-version
  - release

include:
  - project: 'gilden/ci/gitlab-ci-templates'
    ref: 'master'
    file:
    - 'pipelines/eXXcellent-release-Child.gitlab-ci.yml'
----

You pipeline then looks like the following:

.Release Pipeline
//todo update image for tag pipelines
image::Release-Docker-Image-Pipeline.png[]

== Pipeline

.update-version-pipeline
[source, yaml]
----
include::{sourcedir}/update-version.gitlab-ci.yml[]
----

== Usage with release branches

The `update version template` can be used to create a pipeline which supports releasing of artifacts from a release branch instead of the master branch. The https://gitlab.exxcellent.de/gilden/ci/exxcellent-increase-version-tool[exxcellent-versioning-tool] takes care of creating the next reasonable version numbers.

If you want to realise this topic you can use the template the following way:

.gitlab-ci.yml
[source, yaml]
----
stages:
  - release

include:
  - project: 'gilden/ci/gitlab-ci-templates'
    ref: 'master'
    file:
    - 'release.gitlab-ci.yml'

# Creates next major prerelease on master (e.g.: 2.0.0-rc.1 --> 3.0.0-rc.1)
a.major-prerelease:
  extends: .release-template
  variables:
    BUMP_VERSION: "major prerelease"
    MODE: "bump"

# Creates next minor prerelease on master (e.g.: 2.0.0-rc.1 --> 2.1.0-rc.1)
b.minor-prerelease:
  extends: .release-template
  variables:
    BUMP_VERSION: "minor prerelease"
    MODE: "bump"

# Creates release on release branch (e.g.: 2.0.0-rc.1 --> 2.0.0)
a.create-release:
  extends: .release-template
  variables:
    BUMP_VERSION: "patch"
    MODE: "next_version"
  rules:
    - if: $CI_COMMIT_REF_NAME =~ /^release/
      when: manual
    - when: never

# Creates next prerelease on release branch (e.g.: 2.0.0 --> 2.0.1-rc.1 or 2.0.0-rc.1 --> 2.0.1-rc.2)
b.create-prerelease:
  extends: .release-template
  variables:
    BUMP_VERSION: "prerelease"
    MODE: "next_version"
  rules:
    - if: $CI_COMMIT_REF_NAME =~ /^release/
      when: manual
    - when: never

----

.release.gitlab-ci.yml
[source, yaml]
----
stages:
  - set-version
  - push-tag-and-version
  - release

include:
  - project: 'gilden/ci/gitlab-ci-templates'
    ref: 'master'
    file:
    - 'pipelines/eXXcellent-release-Child.gitlab-ci.yml'
    - 'push-image.yml'

# This is optional
push-docker-image:
  extends: .publish-image-kaniko
  stage: release
  # You only need NEED if you use a artifact from your parent pipeline to build the image
  needs:
    - pipeline: $PARENT_PIPELINE_ID
      job: Build
    - job: increase-version
    - job: push-tag-and-version
  rules:
    - when: always
  before_script:
    - "[ -f ./version ] && export LATEST_VERSION=$(cat ./version)"
    - export PARSED_VERSION=$(echo $LATEST_VERSION | sed -r 's/\+/_/g') # Replace + sign since this is not valid in a docker tag
    - export IMAGE_NAME=$CI_REGISTRY_IMAGE:$PARSED_VERSION
----

More information on this topic and a more detailed instructions can be found in our https://gitlab.exxcellent.de/gilden/ci/exxcellent-branching-template[exxcellent-branching-template].