Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 44 ยท GitLab CI/CD

Includes, Templates and Environments

Reuse GitLab CI configuration with include, extends, !reference and hidden jobs, then track deployments with environments, review apps, manual jobs and protected variables.

A .gitlab-ci.yml file grows. After a few months it has five jobs that all begin with the same image and before_script, and a second repository needs nearly the same pipeline. Copy and paste is the enemy: fix a bug in one copy and the others stay broken. GitLab offers three tools to share configuration: include (pull in other files), extends (inherit from another job), and YAML anchors (reuse within one file).

The second half of the lesson turns to deployment. GitLab can track where your code runs through environments, create a temporary copy of the app for each merge request (review apps), require a human click for risky jobs, and keep secrets away from unprotected branches with protected variables.

GitLab cannot run on this site, so the YAML is read-only. The TryIts are JavaScript stand-ins: one merges job definitions the way extends does, the other shows which variables a job can see. They model the rules; they are not GitLab's implementation.

Hidden jobs and extends

A job whose name starts with a dot is hidden: GitLab never runs it. Hidden jobs are templates. Other jobs inherit from them with extends:

YAML
.node-job:
  image: node:22
  variables:
    CI: "true"
  before_script:
    - npm ci
  tags:
    - docker

unit-tests:
  extends: .node-job
  script:
    - npm test

lint:
  extends: .node-job
  variables:
    LINT_STRICT: "1"
  script:
    - npm run lint

The real job lint ends up with image, before_script and tags from the template, its own script, and a variables block that contains both CI and LINT_STRICT.

That last detail is the merge rule you must know:

  • Hashes (mappings) are merged deeply. Keys from the child override keys from the parent, and keys that exist only in the parent are kept.
  • Everything else is replaced. Scalars (image) and arrays (script, before_script, tags) are not merged: if the child defines before_script, the parent's list is gone entirely.
  • extends accepts a list, extends: [.a, .b]; later entries win over earlier ones, and the job's own keys win over all of them.

Try it: merge job definitions

This stand-in resolves extends as described: deep merge for objects, replacement for everything else, parents applied in listed order and the job on top. It also shows !reference, GitLab's way of pulling one part of another job (such as its script list) into an array, here written as { ref: [job, key] } because JavaScript has no YAML tags.

JS Resolve extends and !reference

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Study the three results. lint keeps CI and NODE_ENV from the template and adds LINT_STRICT (deep merge of variables), but its before_script is only ["npm ci --prefer-offline"]: the array was replaced, not extended. In e2e, NODE_ENV becomes "e2e", and the !reference item expands into the two lines of .setup's script.

YAML anchors

Plain YAML has its own reuse: &name labels a block, *name repeats it and <<: *name merges it into a mapping.

YAML
.defaults: &defaults
  image: node:22
  tags: [docker]

unit-tests:
  <<: *defaults
  script: [npm test]

Anchors only work inside one file, so they cannot pull from an included file. extends works across files, which is why it is usually the better choice.

include: configuration from other files

include merges other YAML files into yours before the pipeline is built. There are four sources:

YAML
include:
  - local: ci/node-jobs.yml                # a file in this repository
  - project: platform/ci-templates         # a file in another project
    ref: v2.1.0
    file: /templates/deploy.yml
  - remote: https://example.com/ci/shared.yml   # a public URL
  - template: Jobs/Code-Quality.gitlab-ci.yml   # shipped with GitLab

Points to know:

  • Order. Included files are merged first and your own file is merged last, so your definitions override included ones using the same merge rules as extends.
  • Pin the ref of project includes to a tag or commit (not a moving branch), exactly as you would pin a library version. Otherwise a change in the shared repository can break every pipeline that uses it.
  • Trust. An included file can add jobs that run with your project's variables and runner access. Include only from sources you control or review.
  • A common structure is one small .gitlab-ci.yml that lists includes and a handful of overrides, with the real jobs living in a templates project owned by a platform team.

rules: can also be attached to an include (include: - local: x.yml rules: - if: ...) to include a file conditionally.

Environments

Most pipelines end by deploying somewhere. The environment keyword tells GitLab where, so it can record each deployment:

YAML
deploy-staging:
  stage: deploy
  script:
    - ./deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-production:
  stage: deploy
  script:
    - ./deploy.sh production
  environment:
    name: production
    url: https://www.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual

Under Operate, Environments, GitLab then lists each environment with its latest deployment, commit and link, keeps a history, and lets you re-deploy an older version, which is a simple rollback.

Two details in the example. when: manual makes the production job wait for a person to press play: pipelines can run to staging automatically and stop before production. And a protected environment (set in the project settings) limits who may run jobs targeting it, so a developer can start a pipeline but only members of the release group can deploy to production.

Review apps

A review app is a temporary environment created for a branch or merge request, so reviewers can click a link and see the change running. The name is dynamic:

YAML
deploy-review:
  stage: deploy
  script:
    - ./deploy-review.sh "$CI_ENVIRONMENT_SLUG"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.review.example.com
    on_stop: stop-review
    auto_stop_in: 3 days
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

stop-review:
  stage: deploy
  script:
    - ./teardown-review.sh "$CI_ENVIRONMENT_SLUG"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  variables:
    GIT_STRATEGY: none
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

on_stop names the job that tears the environment down; GitLab runs it when the branch is deleted or the merge request is merged, and auto_stop_in stops forgotten reviews after a time. GIT_STRATEGY: none skips fetching the code in the stop job, because the branch may already be gone. Without a cleanup job, review apps accumulate and cost money.

flowchart LR
    MR["Merge request opened"] --> D["deploy-review<br/>creates review/feature-x"]
    D --> R["Reviewers open the URL"]
    R --> M["MR merged or branch deleted"]
    M --> S["stop-review<br/>(on_stop) removes it"]

A review app lives from the merge request to its cleanup.

Protected variables

Secrets such as a production deploy token live in Settings, CI/CD, Variables. Each variable has flags:

  • Masked hides the value in job logs (the value must satisfy formatting rules such as a minimum length).
  • Protected makes the variable available only in pipelines running on protected branches and tags.
  • An environment scope (for example production, or review/* with a wildcard) limits which environment's jobs can see it.

So a pipeline from an unprotected feature branch, or from a fork, never receives the production token, and a typo in a feature job cannot deploy to production.

Try it: which variables can a job see?

The stand-in filters a list of variables by the protected flag and the environment scope. The same variable name can exist twice with different scopes, as the two DEPLOY_URL entries show.

JS Which variables does this job get?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last two lines show the point: the production job on a protected branch sees DEPLOY_TOKEN and DEPLOY_URL, while the same job on an unprotected branch sees neither. (In the model, a variable with scope * is visible to every job, which also matches how an unscoped GitLab variable behaves; here that is only APP_NAME for jobs without an environment.)

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A hidden job .node-job has before_script: [npm ci]. A job extends it and defines before_script: [npm ci --prefer-offline]. What is the final before_script?

    Arrays are replaced, not merged. Only hashes (mappings) are merged deeply.
  2. 2. Why should a project include pin its ref to a tag?

    A moving branch can change under you. A tag gives a stable version that you upgrade on purpose.
  3. 3. What does on_stop in an environment do?

    on_stop references a stop job, which GitLab triggers when the environment should be removed.
  4. 4. A protected variable is requested by a job running on an unprotected branch. What happens?

    Protected variables are exposed only to pipelines on protected branches and tags.
  5. 5. Where do YAML anchors (&name and <<: *name) work?

    Anchors are resolved by the YAML parser per file. To share across files use extends or include.

Summary

  • Hidden jobs (names starting with a dot) are templates; extends inherits from them. Hashes merge deeply, but scalars and arrays are replaced; !reference pulls a part of another job.
  • include merges files from local, project, remote or template sources; your own file wins, and project includes should be pinned by ref.
  • environment records deployments, offers rollback via history, and can be protected; when: manual adds a human gate.
  • Review apps use dynamic names plus an on_stop cleanup job.
  • Protected, masked and scoped variables keep secrets away from unprotected branches.

Next up in the track is the testing chapter, starting with Test Stages in a Pipeline.