Pin job images by SHA digest, install tools at exact versions and check their checksums, and install dependencies from a lockfile. Each rule removes a place where a changed upstream can alter your build without a review. GitLab's pipeline security guidance recommends all three.
Images
GitLab's pipeline security page says to always use SHA digests for Docker images, to ensure client-side integrity verification. A tag such as latest can point at a different image tomorrow. A digest cannot. It also suggests protected container repositories and protected tags to control who can change images, and to avoid variables in image references, because a variable can be changed to point to a malicious image.
build:
image: node:22@sha256:0000000000000000000000000000000000000000000000000000000000000000
The digest above is a placeholder. Use the real value from your registry.
Tools installed in scripts
When a job downloads a tool, specify and verify the exact version, and check the checksum. A line that fetches whatever is current trusts the download site with your build. Version managers such as nvm pin runtimes.
Dependencies
Use locked, exact installs: npm ci, a frozen lockfile for Yarn, or hash-verified installs for pip, as GitLab lists. See npm ci versus npm install for why.
Includes and components
Pin include references to a commit SHA, protected tag or specific version, and avoid versionless includes. For remote files, GitLab suggests copying them into your repository and including the local copy. See project versus remote includes and components and templates.
| Item | Weak | Better |
|---|---|---|
| Job image | image: node:latest | Tag with digest |
| Tool download | Current release URL | Exact version plus checksum |
| Dependencies | npm install | npm ci with lockfile |
| Include | Branch or no version | SHA or protected tag |
Steps to roll it out
- List every
image,includeand download line in your pipeline files. - Replace moving references with fixed ones, one pipeline at a time.
- Add a scheduled job that checks for newer versions and opens a change for review. Pinning without updating leaves known vulnerabilities in place.
- Scan the pinned image, since a fixed digest can still hold flaws. See container image scanning in CI.
- Require review on pipeline file changes. See CODEOWNERS for pipeline files.
Common mistakes
Teams pin an image tag but not its digest, or pin the job image while the build downloads tools without checksums. Another error is pinning and then never updating, so known flaws live on. Make the update path as easy as the pin: a scheduled job that proposes new digests, a review, and a scan before the change merges.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how a scan reports findings against a specific image, which is why a pinned digest is worth scanning.
Safeguard's dependency and SBOM scanning shows what a pinned build contains, and you can try a free scan at https://gold.safeguard.sh/scan.
Quick check
Does pinning make me safe?
No. It makes the build repeatable. You still need scans and a plan to update.
Which is better, a tag or a digest?
A digest, because a tag can be moved. Keep the tag beside it for readability.
Sources
- GitLab Docs: Pipeline security, fetched 19 October 2026.
Last reviewed: 19 October 2026.
