Setup in a self-managed instance

Prerequisites

• A self-managed GitLab instance with an up-to-date version.
• GitLab Runners for your Instance, Group or Project

Optional: Setup GitLab Runners

• Install GitLab Runner Operator
• Create a GitLab Runners for your Instance, Group or Project
• Configure the variable XDG_CACHE_HOME to point to a shared volume that is RWX. You skip this option to avoid cache poisoning.
• Configure the variable XDG_DATA_HOME to point to a extra volume that is RWO.

Environment Variables for the GitLab Runner

Name	Default value	Required	Encoding	Description	Jobs related
XDG_CACHE_HOME	unset	no	string	Enables caching, Points to a shared volume for Projects and Jobs	All pipelines
XDG_DATA_HOME	unset	no	string	Enables extra storage, Points to a local volume to circumvent ephemeral storage shortage	All pipelines

Setup CI Tools in a self-managed instance

• Create a group xrow-public in your self-managed instance.
• Create a project ci-tools in your self-managed instance.
• Remove the protected branch
• Setup a repository mirror from https://gitlab.com/xrow-public/ci-tools.git with direction pull
• Create a own components group for your company e.g. components
• Create a project mycompany in components
• Create a new component called common by creating the file templates/common/template.yml. Please notice the configuration for the disconnected setup with a external registry.

templates/common/template.yml

spec:
  inputs:
    registry:
      default: "registry.mycompany.com"
    repository-path:
      default: "${CI_PROJECT_PATH}"
    proxy:
      default: false
      type: boolean
---
 
include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
    inputs:
      repo: $[[ inputs.registry ]]/proxy-gitlab/xrow-public/ci-tools
      registry: $[[ inputs.registry ]]
      repository-path: $[[ inputs.repository-path ]]
      stages:
      - prepare
      - lint
      - build
      - test
      - render
      - validate
      - deploy
 
variables:
  CI_REGISTRY_IMAGE: "$[[ inputs.registry | expand_vars ]]/$[[ inputs.repository-path | expand_vars ]]"
  CI_TEMPLATE_REGISTRY_HOST: $[[ inputs.registry ]]/proxy-gitlab

Now you can use your component instead components/mycompany/common of xrow-public/ci-tools/common.

Keep a disconnected instance up to date

Use the pipeline-auto-update component to transfer a selected CI Tools release, its container images, and the Trivy databases into the self-managed instance. The runner for this pipeline is the transfer point: it must be able to reach gitlab.com, registry.gitlab.com, ghcr.io, and the internal GitLab instance and container registry. A fully isolated network therefore needs an approved transfer runner or equivalent controlled network path.

• Create an auto-update project in the self-managed GitLab instance.
• Give the project write access to the internal xrow-public/ci-tools repository. The component's default SSH destination can use a GIT_SSH_KEY file variable whose public key is configured as a write-enabled deploy key.
• Ensure CI_REGISTRY, CI_REGISTRY_USER, and CI_REGISTRY_PASSWORD point to credentials that can push to the internal container registry.
• Add this .gitlab-ci.yml, replacing <current-imported-version> with the numeric CI Tools release that is already available in the internal mirror:

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@<current-imported-version>
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/pipeline-auto-update@<current-imported-version>
    inputs:
      repository: $CI_REGISTRY/components/ci-tools

variables:
  # renovate: datasource=gitlab-releases depName=xrow-public/ci-tools
  TOOLS_VERSION: <current-imported-version>

• Onboard Renovate to the auto-update project and add a default-branch pipeline schedule. The scheduled pipeline checks gitlab.com for a newer CI Tools release and opens an update merge request.
• Review and merge the Renovate merge request. The resulting default-branch pipeline copies the release images and Trivy databases to the internal registry, then moves the internal stable branch to the selected release.
• Confirm that the pipeline succeeds before using the new version. Projects in the disconnected instance can continue to include the internal components with $CI_SERVER_FQDN/xrow-public/ci-tools/...@stable and pull their images from the internal registry configured by the company common component.

Keep the version in both component includes and TOOLS_VERSION identical. This ensures the update pipeline runs with the same release that it transfers.

Service account access token

Configure CI Tools automation with a group service account and the GITLAB_TOKEN variable.