Prefer include:project over include:remote. GitLab's documentation recommends fetching shared configuration from another project on the same instance when possible, because it avoids an external HTTP request. Whichever you use, point it at a fixed ref you control and review changes to the shared file as you would application code.
What each include type does
include:local pulls a file from the same repository.
include:project fetches a file from another project on your GitLab instance. You name the project, a ref and the file path.
include:remote fetches a file over HTTP or HTTPS from a URL.
include:template pulls a template that GitLab provides.
Why this is a security question
An included file becomes part of your pipeline. Whoever can change that file can change what your jobs run, including scripts that see your variables. So the question is not only where the file lives, but who can edit it and whether you pick up edits automatically.
The GitLab page notes that remote fetches can fail for connectivity reasons and that remote hosts may rate-limit requests. It does not describe an integrity or checksum option for remote includes, so treat a remote URL as content you do not control unless you control the host.
Comparison
| Type | Where the file lives | Who can change it | Main concern |
|---|---|---|---|
| local | Same repo | Anyone who can merge there | Normal code review applies |
| project | Another project on your instance | That project's maintainers | Changes flow to every consumer |
| remote | Any URL | Whoever controls the host | No integrity check described, availability |
| template | Provided by GitLab | GitLab, via product upgrades | Behaviour can change on upgrade |
Steps for a safer shared config
- Host shared config in a project you own, and use include:project.
- Set the ref deliberately. The documentation example uses a branch. A branch moves every time someone pushes to it. Check which ref types your GitLab version accepts and prefer a tag or commit you control for stable pipelines.
- Protect that project. Require merge request approval, and limit who can push to the branch or tag you reference.
- Avoid remote includes from hosts you do not control.
- Keep secrets out of shared files, and keep deploy jobs in the project that owns them.
Common mistakes
- Pointing a shared include at a branch that many people can push to, so one careless push changes every pipeline that uses it.
- Letting a template project sit with default permissions while dozens of pipelines depend on it.
- Putting deploy logic in a shared template that any project can include, rather than in the project that owns the deployment.
- Forgetting that a change to a shared file affects every consumer at once, so test changes in a staging project first and announce them.
Quick check
Is include:project always safe?
No. It moves the trust to whoever maintains that project. Protect the branch or tag you reference.
Should I host shared CI config on GitLab Pages?
GitLab's documentation says to avoid it, because GitLab.com Pages is rate limited. Use include:project instead.
Safeguard can enforce policies and gates on merge requests and scan the dependencies those pipelines build. The free scan shows what a repository pulls in.
Sources
Last reviewed: 19 October 2026.
