[feature] Multi-repo workflow

README.md

@@ -21,6 +21,32 @@ Build:
   extends: .build
 ```
 
-> Instead of `/main/`, you can specify a specific commit to ensure changes do not affect your CI. 
+> Instead of `/main/`, you can specify a specific commit to ensure changes do not affect your CI.
 
 The [`examples`](examples/) folder contains examples of `.gitlab-ci.yml` that can be assembled from the templates.
+
+## Multi-repository templates
+
+In `templates/multi-repo` the CI workflow differs from `basic` CI (which in `templates`) in the following key aspects:
+
+- In `multi-repo` workflow we can push to `dev` and `prod` registries separately with their own rules (see `jobs/multi-repo` and/or `examples/multi-repo-module.gitlab-ci.yml` for example jobs).
+- All werf's caches and other artifacts (from `build` stage) are stored in Gitlab's module's registry by default. And **only final images** are pushed to the dev/prod registries. So, even in dev-registry there **should be no** "build-time garbage" and/or some "extra" images/layers for each module.
+
+### Detailed differences between `multi-repo` and `basic` workflows
+
+- [General] There is additional stage `lint` before `build`.
+- [General] All `only` sections (like `only: [tags, branches]`) replaced with corresponding `rules` section.
+- [General] Added `.default_rules` hidden job (see `templates/multi-repo/Setup.gitlab-ci.yml`) for easy modification of this whole workflow.
+- [General] Added `.deploy-prod-rules` hidden job (see `templates/multi-repo/Deploy.gitlab-ci.yml`) for easy modification of `deploy to production` workflow.
+- [General] Added `jobs/multi-repo` jobs files which user can include and use in their own workflow.
+- [Refactor] Default `before_script` section (see `templates/Setup.gitlab-ci.yml`) moved to `.setup/before_script` job.
+- [Refactor] `dmt lint` job moved to `lint` stage in dedicated `templates/multi-repo/Lint.gitlab-ci.yml` file.
+- [Refactor] All werf's caches and other artifacts (from `build` stage) are stored in Gitlab's registry (`${CI_REGISTRY_IMAGE}/${MODULES_MODULE_NAME}`) by default.
+- [Refactor] Images publishing (via `crane copy`) and module's self-registration processes moved to dedicated hidden job `.publish` (see `templates/multi-repo/Deploy.gitlab-ci.yml`).
+
+## Variables
+
+`$MODULES_REGISTRY` - base URL for the registry, e.g. `registry.example.com`
+`$MODULES_REGISTRY_PATH` - path to modules repository in registry, e.g. `deckhouse/modules`
+`$MODULES_MODULE_NAME` (Optional) - module name, by default it is equal to the project name
+`$RELEASE_CHANNEL` - lowercase release channel name, e.g., `alpha`, `stable`, `early-access`

examples/multi-repo-module.gitlab-ci.yml

@@ -0,0 +1,44 @@
+include:
+  - remote: 'https://raw.githubusercontent.com/deckhouse/modules-gitlab-ci/refs/heads/main/templates/multi-repo/Setup.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/deckhouse/modules-gitlab-ci/refs/heads/main/templates/multi-repo/Lint.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/deckhouse/modules-gitlab-ci/refs/heads/main/templates/multi-repo/Build.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/deckhouse/modules-gitlab-ci/refs/heads/main/templates/multi-repo/Deploy.gitlab-ci.yml'
+  # deploy jobs for DEV registry
+  - remote: 'https://raw.githubusercontent.com/deckhouse/modules-gitlab-ci/refs/heads/main/jobs/multi-repo/Deploy_DEV.gitlab-ci.yml'
+  # deploy jobs for PROD registry
+  - remote: 'https://raw.githubusercontent.com/deckhouse/modules-gitlab-ci/refs/heads/main/jobs/multi-repo/Deploy_PROD.gitlab-ci.yml'
+
+variables:
+  # Do not forget to put these variables to your Gitlab CI secrets:
+  # They are REQUIRED and used for pulling/pushing images to the corresponding registry
+  # - DEV_MODULES_REGISTRY: DEV registry domain (like: registry.example.com)
+  # - DEV_MODULES_REGISTRY_PATH: path to modules repository in DEV registry (like: deckhouse/modules)
+  # - DEV_MODULES_REGISTRY_LOGIN: username to log in to DEV registry
+  # - DEV_MODULES_REGISTRY_PASSWORD: password to log in to DEV registry
+
+  # WARNING: If some of following variables are NOT SET, then there is NO production deployment jobs will be created in pipeline
+  # - PROD_MODULES_REGISTRY: PROD registry domain (like: registry.example.com)
+  # - PROD_MODULES_REGISTRY_PATH: path to modules repository in PROD registry (like: deckhouse/modules)
+  # - PROD_MODULES_REGISTRY_LOGIN: username to log in to PROD registry
+  # - PROD_MODULES_REGISTRY_PASSWORD: password to log in to PROD registry
+  WERF_VERSION: "2 stable"
+  BASE_IMAGES_VERSION: v0.2
+
+default:
+  tags:
+    - my-runner-tag
+
+
+###### LINT STAGE ######
+
+Lint:
+  extends: .lint
+
+###### END OF LINT STAGE ######
+
+###### BUILD STAGE ######
+
+Build:
+  extends: .build
+
+###### END OF BUILD STAGE ######

jobs/multi-repo/Deploy_DEV.gitlab-ci.yml

@@ -0,0 +1,20 @@
+# emulate same behaviour as in Deckhouse Github registry
+# when opened PRs will pushed to dev registry
+Publish DEV:
+  extends: .publish
+  variables:
+    MODULES_REGISTRY: ${DEV_MODULES_REGISTRY}
+    MODULES_REGISTRY_PATH: ${DEV_MODULES_REGISTRY_PATH}
+    MODULES_REGISTRY_LOGIN: ${DEV_MODULES_REGISTRY_LOGIN}
+    MODULES_REGISTRY_PASSWORD: ${DEV_MODULES_REGISTRY_PASSWORD}
+    # names as in Github: "pr" + merge request project-level ID instead of branch name
+    MODULES_MODULE_TAG: pr${CI_MERGE_REQUEST_IID}
+  rules:
+    # do not run if some required variables is empty
+    - if: '$DEV_MODULES_REGISTRY == null || $DEV_MODULES_REGISTRY == "" || $DEV_MODULES_REGISTRY_PATH == null || $DEV_MODULES_REGISTRY_PATH == ""'
+      when: never
+    # run only for merge requests
+    - if: $CI_MERGE_REQUEST_IID && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME != $CI_DEFAULT_BRANCH && $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: on_success
+    # do not run in other cases
+    - when: never

jobs/multi-repo/Deploy_PROD.gitlab-ci.yml

@@ -0,0 +1,24 @@
+Deploy to Alpha:
+  extends: .deploy
+  variables:
+    RELEASE_CHANNEL: alpha
+
+Deploy to Beta:
+  extends: .deploy
+  variables:
+    RELEASE_CHANNEL: beta
+
+Deploy to EarlyAccess:
+  extends: .deploy
+  variables:
+    RELEASE_CHANNEL: early-access
+
+Deploy to Stable:
+  extends: .deploy
+  variables:
+    RELEASE_CHANNEL: stable
+
+Deploy to RockSolid:
+  extends: .deploy
+  variables:
+    RELEASE_CHANNEL: rock-solid

templates/Build.gitlab-ci.yml

@@ -43,4 +43,4 @@
         --new_tag "${MODULES_MODULE_SOURCE}:${MODULES_MODULE_NAME}"
   only:
     - tags
-    - branches
+    - branches

templates/Deploy.gitlab-ci.yml

@@ -9,12 +9,12 @@
   script:
   - |
     REPO="${MODULES_MODULE_SOURCE}/${MODULES_MODULE_NAME}/release"
-    
+
     IMAGE_SRC="${REPO}:${MODULES_MODULE_TAG}"
     IMAGE_DST="${REPO}:${RELEASE_CHANNEL}"
-    
+
     echo "✨ Pushing ${IMAGE_SRC} to ${IMAGE_DST}"
     crane copy "${IMAGE_SRC}" "${IMAGE_DST}"
   only:
     - tags
-  when: manual
+  when: manual

templates/Setup.gitlab-ci.yml

@@ -38,4 +38,4 @@ before_script:
   - curl --fail -sSLO https://fox.flant.com/api/v4/projects/deckhouse%2Fbase-images/packages/generic/base_images/${BASE_IMAGES_VERSION}/base_images.yml
 stages:
   - build
-  - deploy
+  - deploy

templates/multi-repo/Build.gitlab-ci.yml

@@ -0,0 +1,15 @@
+.build:
+  stage: build
+  rules:
+    - !reference [.default_rules, rules]
+  before_script:
+    - !reference [.setup, before_script]
+  script:
+    # Build images
+    - |
+      werf build \
+        --save-build-report --build-report-path images_tags_werf.json
+  artifacts:
+    paths:
+      - images_tags_werf.json
+    expire_in: "30 days"

templates/multi-repo/Deploy.gitlab-ci.yml

@@ -0,0 +1,72 @@
+.publish:
+  stage: deploy
+  script:
+    - |
+      # Login to Gitlab (source) registry if target registry is not same Gitlab
+      if [[ "x${MODULES_REGISTRY}" != "x${CI_REGISTRY}" ]]; then
+        echo "Login to Gitlab (source) ${CI_REGISTRY}..."
+        werf cr login -u ${CI_REGISTRY_USER} -p ${CI_REGISTRY_PASSWORD} ${CI_REGISTRY}
+      fi
+
+      # Login to target registry
+      werf cr login -u ${MODULES_REGISTRY_LOGIN} -p ${MODULES_REGISTRY_PASSWORD} ${MODULES_REGISTRY}
+    # generate MODULES_MODULE_SOURCE
+    - |
+      export MODULES_MODULE_SOURCE="${MODULES_REGISTRY}/${MODULES_REGISTRY_PATH}"
+    # Module images
+    - |
+      for image in $(ls images); do
+        IMAGE_SRC="$(jq -r ".Images.\"$image\".DockerImageName" images_tags_werf.json)"
+        IMAGE_TAG="$(jq -r ".Images.\"$image\".DockerTag" images_tags_werf.json)"
+        IMAGE_DST="${MODULES_MODULE_SOURCE}/${MODULES_MODULE_NAME}:${IMAGE_TAG}"
+
+        echo "✨ Pushing ${IMAGE_SRC} to ${IMAGE_DST}"
+        crane copy ${IMAGE_SRC} ${IMAGE_DST}
+      done
+    # Bundle image
+    - |
+      IMAGE_SRC="$(jq -r '.Images."bundle".DockerImageName' images_tags_werf.json)"
+      IMAGE_DST="${MODULES_MODULE_SOURCE}/${MODULES_MODULE_NAME}:${MODULES_MODULE_TAG}"
+
+      echo "✨ Pushing ${IMAGE_SRC} to ${IMAGE_DST}"
+      crane copy ${IMAGE_SRC} ${IMAGE_DST}
+    # Release-channel image
+    - |
+      IMAGE_SRC="$(jq -r '.Images."release-channel-version".DockerImageName' images_tags_werf.json)"
+      IMAGE_DST="${MODULES_MODULE_SOURCE}/${MODULES_MODULE_NAME}/release:${MODULES_MODULE_TAG}"
+
+      echo "✨ Pushing ${IMAGE_SRC} to ${IMAGE_DST}"
+      crane copy ${IMAGE_SRC} ${IMAGE_DST}
+    # Register module
+    - |
+      echo "✨ Register the module ${MODULES_MODULE_NAME}"
+      crane append \
+        --oci-empty-base \
+        --new_layer "" \
+        --new_tag "${MODULES_MODULE_SOURCE}:${MODULES_MODULE_NAME}"
+
+.deploy-prod-rules:
+  rules:
+    # add MANUAL deploy job if $FORCE_CI variable is defined
+    - if: $FORCE_CI
+      when: manual
+    # do not run if some required variables is empty
+    - if: '$PROD_MODULES_REGISTRY == null || $PROD_MODULES_REGISTRY == "" || $PROD_MODULES_REGISTRY_PATH == null || $PROD_MODULES_REGISTRY_PATH == ""'
+      when: never
+    # add MANUAL deploy job only if it is a tag release and release channel is defined
+    - if: '$CI_COMMIT_TAG && $RELEASE_CHANNEL'
+      when: manual
+
+.deploy:
+  stage: deploy
+  rules:
+    - !reference [.deploy-prod-rules, rules]
+  script:
+  - |
+    REPO="${MODULES_REGISTRY}/${MODULES_REGISTRY_PATH}/${MODULES_MODULE_NAME}/release"
+
+    IMAGE_SRC="${REPO}:${MODULES_MODULE_TAG}"
+    IMAGE_DST="${REPO}:${RELEASE_CHANNEL}"
+
+    echo "✨ Pushing ${IMAGE_SRC} to ${IMAGE_DST}"
+    crane copy "${IMAGE_SRC}" "${IMAGE_DST}"

templates/multi-repo/Lint.gitlab-ci.yml

@@ -0,0 +1,10 @@
+.lint:
+  stage: lint
+  rules:
+    - !reference [.default_rules, rules]
+  allow_failure: true
+  before_script:
+    - !reference [.setup, before_script]
+  script:
+    - |
+      dmt lint ./

templates/multi-repo/Setup.gitlab-ci.yml

@@ -0,0 +1,71 @@
+variables:
+  ##############################
+  # User default settings
+  ##############################
+
+  MODULES_MODULE_NAME: "${CI_PROJECT_NAME}"
+  MODULES_MODULE_TAG: ${CI_COMMIT_REF_NAME}
+
+  ##############################
+  # Internal default settings
+  ##############################
+  BASE_IMAGES_VERSION: v0.2
+
+  # use module's container registry (on Gitlab) as werf's intermediate/cache images registry (repo with all build-time artifacts (garbage))
+  WERF_REPO: ${CI_REGISTRY_IMAGE}/${MODULES_MODULE_NAME}
+
+stages:
+  - lint
+  - build
+  - deploy
+
+.default_rules:
+  rules:
+    # run if $FORCE_CI variable is defined
+    - if: '$FORCE_CI'
+    # run if there is a tag defined (module release workflow)
+    - if: '$CI_COMMIT_TAG'
+    # run if there is a merge request event
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
+    # DO NOT run if there is a push to a branch and there are open merge requests (remove duplicated `branch` pipeline)
+    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
+      when: never
+    # run if there is a push to a branch (without opened merge requests)
+    - if: '$CI_COMMIT_BRANCH'
+
+.setup:
+  before_script:
+    # Setup trdl
+    - |
+      trdl_version=$(curl -s https://tuf.trdl.dev/targets/channels/0/stable)
+      curl -sSLO "https://tuf.trdl.dev/targets/releases/$trdl_version/linux-amd64/bin/trdl"
+      install -D trdl ~/bin/trdl
+      rm trdl
+      export PATH=$PATH:~/bin
+
+    # Setup werf
+    - |
+      trdl add werf https://tuf.werf.io 1 b7ff6bcbe598e072a86d595a3621924c8612c7e6dc6a82e919abe89707d7e3f468e616b5635630680dd1e98fc362ae5051728406700e6274c5ed1ad92bea52a2
+      source $(trdl use werf ${WERF_VERSION:-1.2 stable})
+      source $(werf ci-env gitlab --as-file)
+
+      # Login to gitlab registry by default
+      if [[ "x${MODULES_REGISTRY}" == "x" ]]; then
+        MODULES_REGISTRY="${CI_REGISTRY}"
+      fi
+      if [[ "x${MODULES_REGISTRY_LOGIN}" == "x" ]]; then
+        MODULES_REGISTRY_LOGIN="${CI_REGISTRY_USER}"
+      fi
+      if [[ "x${MODULES_REGISTRY_PASSWORD}" == "x" ]]; then
+        MODULES_REGISTRY_PASSWORD="${CI_REGISTRY_PASSWORD}"
+      fi
+      werf cr login -u ${MODULES_REGISTRY_LOGIN} -p ${MODULES_REGISTRY_PASSWORD} ${MODULES_REGISTRY}
+
+    # Setup dmt
+    - |
+      trdl add dmt https://trrr.flant.dev/trdl-dmt/ 0 e77d785600a8c8612b84b93a5a2e4c48188d68f7478356d0708213e928bf67b024ed412e702dc32930da5c5bfc9b1c44be3ee7a292f923327815c91c6c3c3833
+      source $(trdl use dmt 0 stable)
+
+    # Download base images yaml file
+    - env | grep BASE_IMAGES_VERSION
+    - curl --fail -sSLO https://fox.flant.com/api/v4/projects/deckhouse%2Fbase-images/packages/generic/base_images/${BASE_IMAGES_VERSION}/base_images.yml