intermediateGitLab CI/CD

Your GitLab CI pipelines have become unmaintainable with copy-pasted YAML across 30+ projects. How do you implement reusable CI/CD components using includes, extends, YAML anchors, and GitLab CI/CD components? What is the migration strategy?

⚡

Quick Answer

Create a central CI/CD templates repository with reusable job definitions, use include:project for cross-project includes, extends for job inheritance, and migrate to GitLab CI/CD Components (catalog) for versioned, discoverable pipeline building blocks with defined inputs.

Detailed Answer

The DRY Problem in GitLab CI

When organizations grow, teams copy-paste CI/CD configurations, leading to drift, inconsistent security practices, and maintenance nightmares. A fix to the Docker build process needs updating in 30 files. The solution is a layered approach: YAML anchors for intra-file reuse, extends for job inheritance, include for cross-file composition, and CI/CD Components for versioned, cataloged building blocks.

Include Strategies

include:project pulls YAML from another repository—ideal for a central templates repo. include:remote pulls from any URL (useful for open-source templates). include:template uses GitLab's built-in templates. include:local references files within the same project. Templates can be overridden by the including project—jobs defined in includes are merged with local definitions, with local values taking precedence.

CI/CD Components (GitLab 17+)

Components are the evolution of includes—they provide versioned, documented, discoverable pipeline building blocks with declared inputs and outputs. Published to the CI/CD Catalog (like a marketplace), they have semantic versioning, input validation, and usage documentation. Components solve the versioning problem that raw includes have: you can pin to @1.2.3 and upgrade deliberately rather than being broken by upstream changes.

Migration Strategy

Phase 1: Identify common patterns across projects (Docker build, deploy to K8s, security scanning). Phase 2: Extract into a templates repository using include:project with ref pinning. Phase 3: Add versioning via Git tags on the templates repo. Phase 4: Migrate to CI/CD Components for better discoverability and input validation. Each phase is backward-compatible—projects can migrate incrementally.

Governance and Standards

The platform team owns the templates repository with branch protection and code review requirements. Changes go through a testing pipeline that validates templates against sample projects. Use compliance pipelines (Ultimate) to enforce that certain includes cannot be overridden—ensuring security scanning always runs regardless of project-level configuration.

# Central templates repository: ci-templates/docker-build.yml # Reusable Docker build template with configurable inputs .docker-build-template: image: docker:24 services: - docker:24-dind variables: DOCKERFILE_PATH: Dockerfile BUILD_CONTEXT: . DOCKER_BUILDKIT: 1 before_script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY script: - | docker buildx build \ --file $DOCKERFILE_PATH \ --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA \ --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG \ --cache-from type=registry,ref=$CI_REGISTRY_IMAGE:cache \ --cache-to type=registry,ref=$CI_REGISTRY_IMAGE:cache,mode=max \ --push \ $BUILD_CONTEXT # Central templates repository: ci-templates/deploy-k8s.yml .deploy-k8s-template: image: bitnami/kubectl:latest variables: K8S_NAMESPACE: default ROLLOUT_TIMEOUT: 300s script: - kubectl config use-context $KUBE_CONTEXT - kubectl set image deployment/$APP_NAME $APP_NAME=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -n $K8S_NAMESPACE - kubectl rollout status deployment/$APP_NAME -n $K8S_NAMESPACE --timeout=$ROLLOUT_TIMEOUT # --- Consumer project .gitlab-ci.yml --- include: - project: 'platform/ci-templates' ref: 'v2.1.0' # Pin to version! file: - '/docker-build.yml' - '/deploy-k8s.yml' - template: Security/SAST.gitlab-ci.yml stages: - build - test - deploy # Inherit and customize docker-build: stage: build extends: .docker-build-template variables: DOCKERFILE_PATH: build/Dockerfile.production BUILD_CONTEXT: . deploy-staging: stage: deploy extends: .deploy-k8s-template variables: K8S_NAMESPACE: staging APP_NAME: my-service KUBE_CONTEXT: staging-cluster environment: name: staging # --- CI/CD Component (GitLab 17+) --- # templates/docker-build/template.yml spec: inputs: stage: default: build dockerfile: default: Dockerfile context: default: . registry: default: $CI_REGISTRY_IMAGE --- "docker-build-$[[ inputs.stage ]]": stage: $[[ inputs.stage ]] image: docker:24 services: - docker:24-dind script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker buildx build --file $[[ inputs.dockerfile ]] --tag $[[ inputs.registry ]]:$CI_COMMIT_SHA --push $[[ inputs.context ]] # Consumer using CI/CD Component include: - component: gitlab.com/platform/ci-templates/[email protected] inputs: dockerfile: build/Dockerfile stage: build

Your GitLab CI pipelines have become unmaintainable with copy-pasted YAML across 30+ projects. How do you implement reusable CI/CD components using includes, extends, YAML anchors, and GitLab CI/CD components? What is the migration strategy?

More GitLab CI/CD questions