From 5c6060da9dbeeab17c5dbdb54edd621d98a708a0 Mon Sep 17 00:00:00 2001 From: Marcel Feix Date: Mon, 4 Apr 2022 14:01:50 +0200 Subject: [PATCH] feat(Pipeline-eXXcellent-Release): Document releasing Pipeline. --- .../pipelines/eXXcellent-release.adoc | 129 ++++++++++ .../pipelines/update-version-pipeline.adoc | 221 ----------------- .../chapters/pipelines/update-version.adoc | 225 ------------------ .../releasing/release-gitlab-template.adoc | 1 + .../templates/releasing/release-template.adoc | 3 +- documentation/document.adoc | 2 +- documentation/generalInformation.adoc | 2 + .../eXXcellent-release-Child.gitlab-ci.yml | 34 +++ .../eXXcellent-release-Main.gitlab-ci.yml} | 0 pipelines/update-version.gitlab-ci.yml | 48 ---- 10 files changed, 168 insertions(+), 497 deletions(-) create mode 100644 documentation/chapters/pipelines/eXXcellent-release.adoc delete mode 100644 documentation/chapters/pipelines/update-version-pipeline.adoc delete mode 100644 documentation/chapters/pipelines/update-version.adoc create mode 100644 pipelines/release/eXXcellent-release-Child.gitlab-ci.yml rename pipelines/{eXXcellent-release.gitlab-ci.yml => release/eXXcellent-release-Main.gitlab-ci.yml} (100%) delete mode 100644 pipelines/update-version.gitlab-ci.yml diff --git a/documentation/chapters/pipelines/eXXcellent-release.adoc b/documentation/chapters/pipelines/eXXcellent-release.adoc new file mode 100644 index 0000000..48f0653 --- /dev/null +++ b/documentation/chapters/pipelines/eXXcellent-release.adoc @@ -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. +---- + + diff --git a/documentation/chapters/pipelines/update-version-pipeline.adoc b/documentation/chapters/pipelines/update-version-pipeline.adoc deleted file mode 100644 index ad1e97c..0000000 --- a/documentation/chapters/pipelines/update-version-pipeline.adoc +++ /dev/null @@ -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]. - - diff --git a/documentation/chapters/pipelines/update-version.adoc b/documentation/chapters/pipelines/update-version.adoc deleted file mode 100644 index d67a4b9..0000000 --- a/documentation/chapters/pipelines/update-version.adoc +++ /dev/null @@ -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]. - - diff --git a/documentation/chapters/templates/releasing/release-gitlab-template.adoc b/documentation/chapters/templates/releasing/release-gitlab-template.adoc index d1f77e6..0cceb41 100644 --- a/documentation/chapters/templates/releasing/release-gitlab-template.adoc +++ b/documentation/chapters/templates/releasing/release-gitlab-template.adoc @@ -1,5 +1,6 @@ :sourcedir: ../../../../templates/ +[#_release_gitlab_template] = Gitlab Release Template This Template makes it easier to create Gitlab Release from the CI diff --git a/documentation/chapters/templates/releasing/release-template.adoc b/documentation/chapters/templates/releasing/release-template.adoc index 6569d24..7d9df96 100644 --- a/documentation/chapters/templates/releasing/release-template.adoc +++ b/documentation/chapters/templates/releasing/release-template.adoc @@ -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 diff --git a/documentation/document.adoc b/documentation/document.adoc index e1e257e..0a3acce 100644 --- a/documentation/document.adoc +++ b/documentation/document.adoc @@ -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 diff --git a/documentation/generalInformation.adoc b/documentation/generalInformation.adoc index 645c6fa..e9c3295 100644 --- a/documentation/generalInformation.adoc +++ b/documentation/generalInformation.adoc @@ -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. + + diff --git a/pipelines/release/eXXcellent-release-Child.gitlab-ci.yml b/pipelines/release/eXXcellent-release-Child.gitlab-ci.yml new file mode 100644 index 0000000..151a515 --- /dev/null +++ b/pipelines/release/eXXcellent-release-Child.gitlab-ci.yml @@ -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 \ No newline at end of file diff --git a/pipelines/eXXcellent-release.gitlab-ci.yml b/pipelines/release/eXXcellent-release-Main.gitlab-ci.yml similarity index 100% rename from pipelines/eXXcellent-release.gitlab-ci.yml rename to pipelines/release/eXXcellent-release-Main.gitlab-ci.yml diff --git a/pipelines/update-version.gitlab-ci.yml b/pipelines/update-version.gitlab-ci.yml deleted file mode 100644 index ca2d94a..0000000 --- a/pipelines/update-version.gitlab-ci.yml +++ /dev/null @@ -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 \ No newline at end of file