Merge branch 'feature/git-merge-to' into 'dev'

feat(git): new `.git:merge-to` job template to merge a reference

Closes #6

See merge request EOLE/infra/ci-tools!37

docs/GETTING-STARTED.md

@@ -740,3 +740,46 @@ To be used, you need to:
 +    IMAGE_TAG: latest
  ...
 ```
+
+#### Avoid regression after stable release
+
+When the next release is prepared in the `$TESTING_BRANCH`, any fixes
+should be applied to the `$DEV_BRANCH` to avoid regressions.
+
+You can either manually merge the fixes to `$DEV_BRANCH` or use the
+`.git:merge-to` template job to automatically merge the release tag to
+the `$DEV_BRANCH`.
+
+To do so, you need to:
+
+1. include [`templates/Rules.yaml`](#target-when-to-run-jobs) file to
+   define the `.not-on-stable` rules template
+2. include the [`templates/Git.yaml`](templates/Git.yaml) file
+3. be sure to have the `release` stage to your current `stages` in
+   your `.gitlab-ci.yml`
+4. define the `merge-to-dev` job extending [`.git:merge-to`](templates/Git.yaml#L88-L185)
+
+```diff
+--- .gitlab-ci.yaml.orig
++++ .gitlab-ci.yaml
+@@ -60,7 +60,8 @@
+
+
+ ###############################################################################
+-# `release` stage: `semantic-release`, `testing-prerelease`, `tag *`
++# `release` stage: `semantic-release`, `testing-prerelease`,
++#                  `merge-to-dev`, `tag *`
+ ###############################################################################
+ # Create the release versions on `$STABLEE_BRANCH`
+ new-release: {extends: '.semantic-release:stable'}
+@@ -69,6 +70,9 @@
+ # update `release.config.js` variable `betaBranch`
+ testing-prerelease: {extends: '.semantic-release:testing}
+
++# Avoid regression by merging all pre-release fixes to `$DEV_BRANCH`
++merge-to-dev: {extends: '.git:merge-to', variables: {GIT_MERGE_TARGET: $DEV_BRANCH}}
++
+ ## tag contribution branches with a more stable name than `git-${CI_COMMIT_SHORT_SHA}`
+ tag contrib branch:
+   extends:
+```

templates/Git.yaml

@@ -83,4 +83,104 @@
                   --to   "${COMMITLINT_TO}"
                   --verbose'
     - echo -e "\e[0Ksection_end:`date +%s`:commitlint\r\e[0K"
+
+
+#
+# .git:merge-to
+# =============
+#
+# Merge `${GIT_MERGE_SOURCE}` to a `${GIT_MERGE_TARGET}` branch.
+#
+# USAGE
+# =====
+#
+# include:
+#   - project: baby-gnu/ci-tools
+#     ref: main
+#     file: /templates/Git.yaml
+#
+# stages:
+#   - release
+#
+# merge-to-dev: {extends: '.git:merge-to', variables: {GIT_MERGE_TARGET: $DEV_BRANCH}}
+#
+# REQUIREMENTS
+# ============
+#
+# - a `release` stage must be present in your pipeline or it must be
+#   overriden by the extending job to feet your need
+#
+# - the `.on-release-tag` rules templates or it must be overriden by
+#   the extending job to feet your need
+#
+# - a `${GIT_MERGE_TARGET}` branch name
+#
+# - a `${GIT_MERGE_SOURCE}` reference, by default `${CI_COMMIT_TAG}`
+#
+# - a `${GITLAB_TOKEN}` to push the merged `${GIT_MERGE_TARGET}`
+#   branch
+#
+# OPTIONAL VARIABLES
+# ==================
+#
+# - `GIT_AUTHOR_NAME`: name of the optional merge commit author,
+#   extracted from `CI_COMMIT_AUTHOR` by default
+#
+# - `GIT_AUTHOR_EMAIL`: email of the optional merge commit author,
+#   extracted from `CI_COMMIT_AUTHOR` by default
+#
+# - `GIT_COMMITTER_NAME`: name of the optional merge commit committer,
+#   default to `${GIT_AUTHOR_NAME}`
+#
+# - `GIT_COMMITTER_EMAIL`: email of the optional merge commit, default
+#   to `${GIT_AUTHOR_EMAIL}`
+#
+# - `GIT_MERGE_TO_IMAGE`: name of the docker image to execute `git`
+#   commands
+#
+# USED CI VARIABLES
+# =================
+#
+# - `CI_COMMIT_TAG`
+#
+# - `CI_COMMIT_AUTHOR`
+#
+# - `CI_REPOSITORY_URL`
+#
+# - `CI_JOB_TOKEN`
+#
+.git:merge-to:
+  stage: release
+  extends: .on-release-tag
+  image: "${GIT_MERGE_TO_IMAGE}"
+  variables:
+    GIT_MERGE_TO_IMAGE: 'bitnami/git:latest'
+    GIT_MERGE_SOURCE: ${CI_COMMIT_TAG}
+    GIT_MERGE_TARGET: ''
+  script:
+    # Configure git to be able to create merge commit
+    # Extract author name and mail if not SET
+    - echo -e "\e[0Ksection_start:`date +%s`:git-configure[collapsed=true]\r\e[0KConfigure git variables from '${CI_COMMIT_AUTHOR}'"
+    - export GIT_AUTHOR_NAME="${GIT_AUTHOR_NAME:-${CI_COMMIT_AUTHOR% <*}}"
+    - export TEMP_MAIL_PREFIX="${CI_COMMIT_AUTHOR#*<}"
+    - export GIT_AUTHOR_EMAIL="${GIT_AUTHOR_EMAIL:-${TEMP_MAIL_PREFIX%>}}"
+    - export GIT_COMMITTER_NAME="${GIT_COMMITTER_NAME:-${GIT_AUTHOR_NAME}}"
+    - export GIT_COMMITTER_EMAIL="${GIT_COMMITTER_EMAIL:-${GIT_AUTHOR_EMAIL}}"
+    - echo -e "\e[0Ksection_end:`date +%s`:git-configure\r\e[0K"
+    # Add `upstream` remote to get access to `upstream/dev`
+    # Use `${GITLAB_TOKEN}` for write permission
+    - echo -e "\e[0Ksection_start:`date +%s`:git-remote-upstream-add[collapsed=true]\r\e[0KAdd upstream repository and checkout '${GIT_MERGE_TARGET}'"
+    - "git remote show upstream 2> /dev/null || git remote add upstream ${CI_REPOSITORY_URL/${CI_JOB_TOKEN}/${GITLAB_TOKEN}}"
+    - 'git fetch --all'
+    - 'git checkout -B ${GIT_MERGE_TARGET} upstream/${GIT_MERGE_TARGET}'
+    - echo -e "\e[0Ksection_end:`date +%s`:git-remote-upstream-add\r\e[0K"
+    # Merge the release tag
+    - echo -e "\e[0Ksection_start:`date +%s`:git-merge-release[collapsed=true]\r\e[0KMerge '${GIT_MERGE_SOURCE}' in '${GIT_MERGE_TARGET}'"
+    - 'git merge --no-edit ${GIT_MERGE_SOURCE}'
+    - 'git push upstream ${GIT_MERGE_TARGET}'
+    - echo -e "\e[0Ksection_end:`date +%s`:git-merge-release\r\e[0K"
+    # Remove `upstream` to avoid caching `${GITLAB_TOKEN}`
+    - echo -e "\e[0Ksection_start:`date +%s`:git-cleanup[collapsed=true]\r\e[0KCleanup git repository"
+    - "git remote remove upstream"
+    - echo -e "\e[0Ksection_end:`date +%s`:git-cleanup\r\e[0K"
 ...