diff --git a/documentation/chapters/pipelines/update-version.adoc b/documentation/chapters/pipelines/update-version.adoc new file mode 100644 index 0000000..d67a4b9 --- /dev/null +++ b/documentation/chapters/pipelines/update-version.adoc @@ -0,0 +1,225 @@ +: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]. + +