Includes, templates and components
Share pipeline code across projects, and pin it so nobody else changes your pipeline.
cd ~/lab && curl -fsSLO https://secopslog.com/lab-files/ci-gitlab/reuse.tar.gz && tar -xzf reuse.tar.gz, which creates ~/lab/reuse/. SHA-256: e37ba454df69c51a2ac7307186c505ec920b441fa453d92202425ddee5b504c7Thirty projects copy the same test job. When the Python version changes, someone opens thirty merge requests. So the platform team moves the job into a shared project and every pipeline includes it. That fixes the copies and creates a new kind of dependency: whoever controls the shared file now controls thirty pipelines, including the jobs that hold their secrets.
A shared templates project
The lab has two projects. ci-templates holds shared configuration and has two tags on the same commit: v1.0.0 for the plain include, and 1.0.0 because components are versioned with plain semantic version numbers. app uses it in several ways:
# Shared job definitions. Hidden jobs (names starting with a dot) never run on their own..python:image: secopslog-py:3.15before_script:- python --version.python-test:extends: .pythonscript:- python -m pytest -q.audit:script:- echo "commit $CI_COMMIT_SHORT_SHA built by $GITLAB_USER_LOGIN"
# A CI/CD component: a template with typed inputs, included by path and version.spec:inputs:paths:default: "."stage:default: test---ruff:stage: $[[ inputs.stage ]]image: secopslog-py:3.15script:- ruff check $[[ inputs.paths ]]
include:- project: root/ci-templatesref: v1.0.0 # a tag: this file changes only when you change this linefile: /templates/python.yml- component: $CI_SERVER_FQDN/root/ci-templates/lint@1.0.0inputs:paths: calc.py- project: root/ci-templatesref: main # a branch: whoever can push to it changes your pipelinefile: /templates/notify.ymltest:extends: .python-testreport:extends: .pythonscript:- !reference [.audit, script]- echo "tests are in the test job"
| Mechanism | What it does | Here |
|---|---|---|
include: project | Pulls YAML from another project at a ref | python.yml at tag v1.0.0, notify.yml at branch main |
extends | Merges a (usually hidden) job into this one | test extends .python-test, which extends .python |
!reference | Reuses one part of another job, such as its script | report takes .audit's script lines |
component | A versioned template with typed inputs | lint@1.0.0 with paths: calc.py |
$CI_SERVER_FQDN in the component path is this GitLab's host name, and the .post stage is a built-in stage that always runs last. Jobs whose names start with a dot are hidden: they never run, they only exist to be extended. A component lives in a templates/ directory and declares its inputs in a spec: header. The component uses its inputs through $[[ inputs.name ]] placeholders, and the caller passes values under inputs:. An unknown input name fails the pipeline instead of passing silently.
Run it, and see what it really runs
Four jobs, none of them written out in full in app's file. To review what a pipeline will actually run, read the merged configuration, which the lint API returns with every include pulled in:
That expanded view is what a reviewer should look at for a pipeline change, because the file in the merge request may be three lines that pull in three hundred.
A branch include moves under you
notify.yml is included from main, so it changes whenever someone pushes to the templates project. Play that someone:
Nothing changed in app. No merge request there, no review there, and its next pipeline ran a new command that talks about its job token. In a real attack that line would send the token, or any variable the job can see, to the attacker. Every project that includes from a branch trusts everyone who can push to that branch, on top of its own developers.
| Reference | Can change under you? | Use for |
|---|---|---|
Branch (ref: main) | Yes, on every push | Your own experiments, never shared CI |
Tag (ref: v1.0.0, @1.0.0) | Only if tags can be moved: protect them | Normal use, together with protected tags |
| Commit SHA | No | Where you need certainty, such as release pipelines |
~latest and partial versions such as @1.0 move with every new release. Pinning the top-level include doesn't pin what it pulls in either: an included file can include others from a branch, or use an image by tag. Always write ref: (without it you get the default branch), and pin images by digest.Hands-on
Pin notify.yml to the commit before the change (git -C templates rev-parse HEAD~1) by putting that SHA in ref:, push, and check the notify job. Then push another change to templates/templates/notify.yml on main and run app's pipeline again with ./run-pipeline.sh app. Does app see it? Finish with ./down.sh.
What you should see: after the pin, ref: holds a 40-character SHA and notify prints notify: pipeline 3 finished, the version from before the change. After a new commit to notify.yml on the templates project's main, app's next pipeline still prints the same single line. and one more thing never appears, because app asks for a commit, and a commit can't change. The cost is that you also don't get fixes until you move the SHA yourself.
Remember
Shared CI configuration is code that runs with your project's secrets. Include it by tag or SHA, protect the tags, and review the merged configuration, not just the file that includes it.
templates/deploy.yml from a shared project with ref: main. What does that mean for its security?app without any change in app..python-test?include: lines. Why is the merged configuration worth reading?