Rules / GL003

GL003 Unpinned include ref

Severity: error
OWASP: CICD-SEC-3 – Dependency Chain Abuse

Risk

Including a remote template without pinning ref to a specific commit SHA means the template content can change at any time. A compromised upstream repository or a force-push to the referenced branch can inject malicious jobs into every pipeline that includes it — without touching the repository itself.

Include types and their treatment

Type	Treatment
`local:`	Always safe — file is in the same repository
`template:`	Always safe — GitLab-managed, versioned with GitLab itself
`component:`	Flagged if `@version` is missing or uses a mutable ref
`project:`	Flagged if `ref:` is absent or points to a mutable branch
`remote:`	Flagged unless `integrity:` pins the content with a `sha256-<base64>` hash

Mutable refs (flagged)

main, master, develop, dev, HEAD, latest, stable, trunk, staging, production, nightly, canary, edge

For component includes, ~latest (GitLab's floating SemVer constraint) is also flagged.

Everything else (version tags, SHAs) is trusted.

Trigger examples

include:
  - project: company/ci-templates
    file: /jobs/build.yml
    # no ref — defaults to HEAD of default branch

  - project: company/ci-templates
    file: /jobs/deploy.yml
    ref: main                  # mutable branch ref

  - remote: https://example.com/template.yml   # URL content is mutable and unverified

Safe alternative

include:
  - project: company/ci-templates
    file: /jobs/build.yml
    ref: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2   # full SHA pin

  - component: gitlab.com/org/component/job@1.0.0   # pinned version tag

  - remote: https://example.com/template.yml
    integrity: sha256-L3/GAoKaw0Arw6hDCKeKQlV1QPEgHYxGBHsH4zG1IY8=   # content pinned (GitLab 17.9+)

With include:integrity, GitLab refuses the include and fails the pipeline when the fetched file does not match the hash. Only a literal sha256- value counts; a hash taken from a variable is still flagged. Plain http:// URLs are still reported by GL016.

Notes

Requires GitLab 15.0+ for component: includes (see #50).

Documentation for glsec 1.23.0. Source of this page · Rule implementation