Anchors Reuse Configuration Deployment Jobs

In this lesson you’ll learn how YAML anchors let you define reusable configuration once and reference it across multiple GitLab CI/CD jobs. Anchors reduce duplication, keep your .gitlab-ci.yml DRY, and make it easier to maintain shared settings like container images, before_script commands, caches, and dependencies.

Quick anchor primer

&name — define an anchor
*name — reference an anchor
<<: — YAML merge key to merge an anchored mapping into another mapping

Basic example — define an anchor and reference it:

.default_scripts: &default_scripts
  - ./default-script1.sh
  - ./default-script2.sh

job1:
  script: *default_scripts

You can also merge (extend) an entire job configuration using the YAML merge key (<<:). Hidden jobs (names that start with a dot) are commonly used in GitLab CI as templates:

.job_template: &job_configuration
  image: ruby:2.6
  services:
    - postgres
    - redis

test1:
  <<: *job_configuration
  script:
    - echo "test1 project"

test2:
  <<: *job_configuration
  script:
    - echo "test2 project"

Anchors can be applied at different granularities: an entire job template, or specific keywords like services or before_script. Example with a job template anchor and service-list anchors:

.job_template: &job_configuration
  script:
    - echo "test project"
  tags:
    - dev

.postgres_services:
  services: &postgres_configuration
    - postgres
    - ruby

.mysql_services:
  services: &mysql_configuration
    - mysql
    - ruby

test:postgres:
  <<: *job_configuration
  services: *postgres_configuration
  tags:
    - postgres

test:mysql:
  <<: *job_configuration
  services: *mysql_configuration
  tags:
    - mysql

Use YAML anchors (&/* and <<:) to merge YAML fragments at parse time. Use extends when you want GitLab-specific job inheritance that can combine rules, needs, or variables in GitLab-specific ways. You can use anchors and extends together where appropriate.

Apply anchors to a GitLab pipeline — a real example

In this project we already have a hidden job .prepare_nodejs_environment used by unit_testing and code_coverage. We want to reuse the same image, dependencies, and a before_script (that installs kubectl and envsubst) across both the dev and stage Kubernetes deployment jobs. Example slice of the pipeline (abbreviated):

workflow: ...
stages: ...
variables: ...

.prepare_nodejs_environment:
  image: node:17-alpine3.14
  services:
    - name: siddharth67/mongo-db:non-prod
      alias: mongo
      pull_policy: always
  variables:
    MONGO_URI: 'mongodb://mongo:27017/superData'
    MONGO_USERNAME: non-prod-user
    MONGO_PASSWORD: non-prod-password
  cache:
    policy: pull-push
    when: on_success

Visualize your pipeline to confirm the current job graph and stages:

A screenshot of the GitLab Pipeline Editor showing a visual pipeline with stages labeled "test", "containerization", "dev-deploy" and "stage-deploy." It displays jobs like unit_testing, docker_build, docker_push and k8s_stage_deploy, and a banner noting "Your changes have been successfully committed."

Example: a simple dev deploy job using `needs`

This k8s_dev_deploy job is intended to start as soon as docker_push completes. Using needs makes that explicit:

k8s_dev_deploy:
  stage: dev-deploy
  needs:
    - docker_push
  image:
    name: alpine:3.7
  dependencies: []
  before_script:
    - wget https://storage.googleapis.com/kubernetes-release/release/$(wget -q -O - https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
    - chmod +x ./kubectl
    - mv ./kubectl /usr/bin/kubectl
    - apk add --no-cache gettext
    - envsubst -V
  script:
    - export KUBECONFIG=$DEV_KUBE_CONFIG
    - kubectl version -o yaml
    - kubectl config get-contexts
    - kubectl get nodes

Create a reusable hidden anchor for the deploy environment

Define a hidden job near the top of the file to hold the shared deploy configuration. Use a clear anchor name and reference it from your deploy jobs:

# Hidden preparatory jobs
.prepare_nodejs_environment: ~

.prepare_deployment_environment: &kubernetes_deploy_job
  image:
    name: alpine:3.7
  dependencies: []
  before_script:
    - wget https://storage.googleapis.com/kubernetes-release/release/$(wget -q -O - https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
    - chmod +x ./kubectl
    - mv ./kubectl /usr/bin/kubectl
    - apk add --no-cache gettext
    - envsubst -V

Now merge that anchor into the dev and stage deploy jobs using the YAML merge key (<<:) with the alias *kubernetes_deploy_job. Add job-specific fields (like stage, needs, when, and the script) after the merge so they can override or extend the merged values. k8s_dev_deploy (merge + job-specific script and needs):

k8s_dev_deploy:
  <<: *kubernetes_deploy_job
  stage: dev-deploy
  needs:
    - docker_push
  script:
    - export KUBECONFIG=$DEV_KUBE_CONFIG
    - kubectl version -o yaml
    - kubectl config get-contexts
    - kubectl get nodes
    - export INGRESS_IP=$(kubectl -n ingress-nginx get services ingress-nginx-controller -o jsonpath="{.status.loadBalancer.ingress[0].ip}")
    - echo $INGRESS_IP
    - kubectl -n $NAMESPACE create secret generic mongo-db-creds --from-literal=MONGO_URI=$MONGO_URI --from-literal=MONGO_USERNAME=$MONGO_USERNAME --from-literal=MONGO_PASSWORD=$MONGO_PASSWORD --save-config --dry-run=client -o yaml | kubectl apply -f -
    - for i in kubernetes/manifest/*.yaml; do envsubst < $i | kubectl apply -f -; done

k8s_stage_deploy (merge + manual trigger + stage-specific actions):

k8s_stage_deploy:
  <<: *kubernetes_deploy_job
  stage: stage-deploy
  when: manual
  script:
    - temp_kube_config_file=$(printenv KUBECONFIG)
    - cat $temp_kube_config_file
    - kubectl config get-contexts
    - kubectl config use-context demos-group/solar-system:kk-gitlab-agent
    - kubectl get po -A
    - export INGRESS_IP=$(kubectl -n ingress-nginx get services ingress-nginx-controller -o jsonpath="{.status.loadBalancer.ingress[0].ip}")
    - echo $INGRESS_IP
    - kubectl -n $NAMESPACE create secret generic mongo-db-creds --from-literal=MONGO_URI=$MONGO_URI --from-literal=MONGO_USERNAME=$MONGO_USERNAME --from-literal=MONGO_PASSWORD=$MONGO_PASSWORD --save-config --dry-run=client -o yaml | kubectl apply -f -
    - for i in kubernetes/manifest/*.yaml; do envsubst < $i | kubectl apply -f -; done
    - kubectl -n $NAMESPACE get all,secret,ing
    - echo "INGRESS_URL=$(kubectl -n $NAMESPACE get ing -o jsonpath='{.items[0].spec.tls[0].hosts[0]}')" >> app_ingress_url.env
  artifacts:
    reports:
      dotenv: app_ingress_url.env
  environment:
    name: staging
    url: https://$INGRESS_URL

Notes on correctness and common pitfalls

Topic	Guidance
Anchor naming	Use a single, consistent anchor name (e.g. `&kubernetes_deploy_job`) and reference it with `*kubernetes_deploy_job`.
Merge semantics	`<<:` inserts mapped keys from the anchor into the job. Keys you add after the merge override merged values.
Long/complex commands	Keep complex shell logic in `script` lines or, better, in scripts checked into the repo to improve readability and maintainability.
JSONPath in `kubectl`	When using `kubectl -o jsonpath="..."`, keep the entire JSONPath expression inside quotes to avoid MDX/YAML parsing issues.
Combining with `extends`	Anchors operate at YAML parse time. Use `extends` for GitLab-specific inheritance where you need behavior beyond YAML merging.

Confirm the environments and agent After committing the changes to your branch a pipeline will be triggered. Validate environments and agent connectivity in GitLab to ensure deployments succeed:

Screenshot of a GitLab "Environments" page listing active environments (development, staging) with deployment status badges, job/branch details, and the left-side project navigation.

A screenshot of the GitLab web UI on the Kubernetes clusters page, showing an agent section with a connected agent named "kk-gitlab-agent" and a banner about Google Cloud credits. The left sidebar displays navigation items like Code, Build, Secure, Deploy and Kubernetes clusters.

Pipeline run and job logs

When the pipeline runs, both k8s_dev_deploy and k8s_stage_deploy will use the alpine:3.7 image and the shared before_script from the anchor. An abbreviated example of the job log showing before_script actions:

Using Docker executor with image alpine:3.7 ...
Pulling docker image alpine:3.7 ...
$ wget https://storage.googleapis.com/kubernetes-release/release/$(wget -q -O - https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
Connecting to storage.googleapis.com ...
kubectl         100% |*******************************|  48540k  0:00:00 ETA
$ chmod +x ./kubectl
$ mv ./kubectl /usr/bin/kubectl
$ apk add --no-cache gettext
(1/8) Installing libgomp ...
(8/8) Installing gettext ...
OK: 16 MiB in 21 packages
$ envsubst -V
envsubst (GNU gettext-runtime) 0.19.8.1

Final pipeline visualization After commits and job execution, the pipeline visualization will reflect the needs dependency (the dev deploy starts when docker_push completes) and both deployment jobs will report their statuses:

A GitLab CI/CD pipeline screenshot titled "Solar System NodeJS Pipeline" showing a passed run with containerization, dev-deploy, and stage-deploy stages and green check marks for completed jobs. The left sidebar shows the project navigation with Pipelines highlighted.

That’s how to use YAML anchors in GitLab CI to reuse deployment configuration across multiple jobs. Another related technique is the !reference tag, which behaves differently from anchors and extends and can be useful for more advanced reuse patterns.

Introduction

Architecture & Core Concepts

Continuous Integration with GitLab

Continuous Deployment with GitLab

Optimization, Security and Monitoring

Self-Managed Runners

Auto DevOps

Anchors Reuse Configuration Deployment Jobs

Quick anchor primer

Apply anchors to a GitLab pipeline — a real example

Example: a simple dev deploy job using `needs`

Create a reusable hidden anchor for the deploy environment

Notes on correctness and common pitfalls

Pipeline run and job logs

Links and references

Watch Video

​Quick anchor primer

​Apply anchors to a GitLab pipeline — a real example

​Example: a simple dev deploy job using needs

​Create a reusable hidden anchor for the deploy environment

​Notes on correctness and common pitfalls

​Pipeline run and job logs

​Links and references

Watch Video

Quick anchor primer

Apply anchors to a GitLab pipeline — a real example

Example: a simple dev deploy job using `needs`

Create a reusable hidden anchor for the deploy environment

Notes on correctness and common pitfalls

Pipeline run and job logs

Links and references