: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.
You also can use the pipelines independently.

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.
When executed on it also creates a new Release Branch.

You can easily extend the child pipeline to publish Artefacts.
Although this is possible we recommend using tagged pipelines to publish Artefacts.
Tagged pipelines have the benefit that your pipelines are linked to a tag.
This makes publishing out of order or hotfixes simpler.
Since you do not relly on prior CI artefacts.

== Overview diagram

The following diagram shows how the pipelines works.
The imported Main pipeline triggers a child-pipeline.
This child pipeline is defined by a yaml file within your repository named release.gitlab-ci.yml Within this file you can define your skripts like in the normal .gitlab-ci.yml file.
We suggest importing the child pipeline.

[mermaid]
....
graph TB
main-project[.gitlab-ci.yml] -- Imports --> main
release[release.gitlab-ci.yml] -- Imports --> child
main -. Triggers Child Pipeline .-> release

subgraph project [Your project]
main-project
release

end

subgraph Gitlab-CI-templates [Gitlab-CI templates]

main[pipelines/release/eXXcellent-release-Main.gitlab-ci.yml]
child[pipelines/release/eXXcellent-release-Child.gitlab-ci.yml]

end
....

== Deep dive

=== Main

The main mainly imports jobs from the release.gitlab-ci.yml file.
On your default branch (Main/Master) it provides a job to increase the Major version.
On all branches that have RELEASE in their name it will provide jobs for all other versions.
This will Trigger your release.gitlab-ci.yml file.
Please read the documentation on <<_release_template>> if you need more information.

It also contains a job to create a Gitlab-Release.
It is only executed within tagged pipelines, since we want to create releases from these Tags.
For More Information about this please read <<_release_gitlab_template>>.

.pipelines/release/eXXcellent-release-Main.gitlab-ci.yml
[source,yaml]
----
include::../../../pipelines/release/eXXcellent-release-Main.gitlab-ci.yml[]
----

=== Child

The child pipeline manly imports the set-version Template.
it consists of two Jobs. The increase-version Job and the Push Tag and Branch Job.

The increase version job searches the latest tag on the branch that is checked out and increases the version according to the passed version type (Major,Minor,usw...).
On release-branches the tag will be pushed from this job. Since we do not need to do more.
On the default branch the push-tag-and-branch will push the tag.
It will also push a RELEASE branch.

When pushing a tag a new tagged pipeline is created.
The release will then be created from this pipeline.
In this pipeline the $CI_COMMIT_TAG variable will be set with the content of the tag.

You can do additional work and publishing here.

.pipelines/release/eXXcellent-release-Child.gitlab-ci.yml
[source,yaml]
----
include::../../../pipelines/release/eXXcellent-release-Child.gitlab-ci.yml[]
----

== Setup

1. to get started you have to prepair the repository so we can push Tags and Branches.
please read this documentation https://www.exxcellent.de/confluence/pages/viewpage.action?pageId=111183261[Getting Started - Version Tool]

2. Then Import the main pipeline into your .gitlab-ci.yml file:

.gitlab-ci.yml
[source,yaml]
----
stages:
  - release #Should be the last stage within you pipeline.

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

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

.release.gitlab-ci.yml
[source,yaml]
----
include:
  - project: 'gilden/ci/gitlab-ci-templates'
    ref: '2.0'
    file:
    - 'pipelines/release/eXXcellent-release-Child.gitlab-ci.yml'

#add more jobs here if needed.
----


