feat(Pipeline-eXXcellent-Release): Document releasing Pipeline.

This commit is contained in:
Marcel Feix 2022-04-04 14:01:50 +02:00
parent c827e39fc5
commit 5c6060da9d
No known key found for this signature in database
GPG Key ID: 04D016E104A25F03
10 changed files with 168 additions and 497 deletions

View File

@ -0,0 +1,129 @@
: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.
----

View File

@ -1,221 +0,0 @@
:sourcedir: ../../../pipelines
ifndef::imagesdir[]
:imagesdir: ../../images
endif::[]
[#_pipeline_release]
= Release Version Pipeline
//todo umschreiben auf tag pipelines.
This pipeline provides the jobs to increase the version, create a new tag and updates the changed files (version) the repository.
It can be extended to push a docker image to a docker registry.
== 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/update-version.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/update-version.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].

View File

@ -1,225 +0,0 @@
: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].

View File

@ -1,5 +1,6 @@
:sourcedir: ../../../../templates/
[#_release_gitlab_template]
= Gitlab Release Template
This Template makes it easier to create Gitlab Release from the CI

View File

@ -1,11 +1,10 @@
:sourcedir: ../../../../templates/
[#_release_template]
= Release Template
This collection provides multiple templated to make publish releases of your Software as easy as possible.
.Angebotene Templates:
|===
|Name |Description

View File

@ -100,7 +100,7 @@ include::chapters/templates/documentation/tool-documentation-tool.adoc[leveloffs
[#_pipelines]
=== Pipelines
include::chapters/pipelines/update-version-pipeline.adoc[leveloffset=3]
include::chapters/pipelines/eXXcellent-release.adoc[leveloffset=3]
//todo docs for new pipelines
//In particular docs for the keyword needs hinzufügen. needs container build step. artefacts true

View File

@ -48,3 +48,5 @@ test-image:
Um Pipelines zu benutzen, müssen diese nur mit `Include` importiert werden.
Für weitere Informationen ließ bitte die Doku der Pipelines selbst.

View File

@ -0,0 +1,34 @@
stages:
- set-version
- push-tag
include:
- local: 'templates/releasing/set-version.gitlab-ci.yml'
variables:
BUMP_VERSION: "major"
increase-version:
rules:
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_REF_NAME == 'Templates2.0'
- if: $CI_COMMIT_REF_NAME ~= 'RELEASE'
variables:
TAG: "true"
before_script:
- setup-ssh
extends: .set-version
push-tag-and-branch:
stage: push-tag
image: gitlab.exxcellent.de:4567/gilden/ci/exxcellent-ssh-tool:1.4.0
rules:
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_REF_NAME == 'Templates2.0'
before_script:
- setup-ssh
- echo $VERSION
- pull
script:
- git checkout -b RELEASE-$VERSION
- git push origin RELEASE-$VERSION $VERSION

View File

@ -1,48 +0,0 @@
stages:
- set-version
- push-tag
include:
- local: 'templates/releasing/set-version.gitlab-ci.yml'
variables:
BUMP_VERSION: "major"
increase-version:
extends: .set-version
push-tag-and-branch:
stage: push-tag
image: gitlab.exxcellent.de:4567/gilden/ci/exxcellent-ssh-tool:1.4.0
rules:
- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_REF_NAME == 'Templates2.0'
before_script:
- setup-ssh
- echo $VERSION
- pull
script:
- git checkout -b RELEASE-$VERSION
- git push origin RELEASE-$VERSION $VERSION
#I would like to use this.
#I think this could be more stable in the long run
#But it is not working: https://github.com/jdalrymple/gitbeaker/issues/2398
#push-tag-and-branch:
# stage: push-tag
# image: node:lts-buster-slim
# variables:
# GITLAB_HOST: $CI_SERVER_URL
# CI_DEBUG_TRACE: "true"
# rules:
# - if: $CI_COMMIT_REF_NAME == 'Templates2.0'
# script:
# - echo "Create version $VERSION"
# - npm -g install @gitbeaker/cli
# - >
# NODE_EXTRA_CA_CERTS=$CI_SERVER_TLS_CA_FILE gitbeaker branches create
# --project-id $CI_PROJECT_ID
# --branch-name RELEASE-$VERSION
# --ref $CI_COMMIT_SHA
# --gb-job-token="$CI_JOB_TOKEN"
# - NODE_EXTRA_CA_CERTS=$CI_SERVER_TLS_CA_FILE gitbeaker tag create --project-id $CI_PROJECT_ID --tag-name $VERSION --ref $CI_COMMIT_SHA