git.stella-ops.org/deploy/gitlab

StellaOps GitLab CI Templates

Production-ready GitLab CI templates for keyless signing integration with StellaOps.

Quick Start

Include the templates in your .gitlab-ci.yml:

include:
  - project: 'stella-ops/templates'
    file: 'deploy/gitlab/examples/.gitlab-ci-stellaops.yml'

sign-my-image:
  extends: .stellaops-sign
  variables:
    ARTIFACT_DIGEST: $IMAGE_DIGEST
    ARTIFACT_TYPE: image

Available Templates

.stellaops-sign

Signs artifacts using keyless signing with Fulcio certificates.

Variables:

Variable	Required	Default	Description
ARTIFACT_DIGEST	Yes	-	SHA256 digest of artifact to sign
ARTIFACT_TYPE	No	image	Type: image, sbom, verdict, report
INCLUDE_REKOR	No	true	Log to Rekor transparency log
PUSH_ATTESTATION	No	true	Push attestation to registry

Outputs (dotenv):

• ATTESTATION_DIGEST: Digest of created attestation
• REKOR_UUID: Rekor transparency log UUID
• CERTIFICATE_IDENTITY: OIDC identity from certificate

.stellaops-verify

Verifies attestations before deployment.

Variables:

Variable	Required	Default	Description
ARTIFACT_DIGEST	Yes	-	SHA256 digest to verify
CERTIFICATE_IDENTITY	Yes	-	Expected identity pattern (regex)
CERTIFICATE_OIDC_ISSUER	No	https://gitlab.com	Expected OIDC issuer
REQUIRE_REKOR	No	true	Require Rekor proof
STRICT	No	true	Fail on any issue

Outputs (dotenv):

• VERIFIED: Whether verification passed
• ATTESTATION_COUNT: Number of attestations found

.stellaops-sbom

Generates, signs, and attaches SBOM to image.

Variables:

Variable	Required	Default	Description
IMAGE	Yes	-	Image to generate SBOM for
SBOM_FORMAT	No	cyclonedx-json	SBOM format
SBOM_OUTPUT	No	sbom.json	Output filename

.stellaops-verdict

Evaluates policy and signs the verdict.

Variables:

Variable	Required	Default	Description
IMAGE	Yes	-	Image to evaluate
POLICY	No	default	Policy pack ID
FAIL_ON_BLOCK	No	true	Fail job if blocked

Identity Patterns for GitLab

When verifying, use these identity patterns:

Constraint	Pattern
Any ref in project	project_path:<group>/<project>:.*
Main branch only	project_path:<group>/<project>:ref_type:branch:ref:main
Protected refs	project_path:<group>/<project>:ref_protected:true
Tags	project_path:<group>/<project>:ref_type:tag:ref:.*

OIDC Issuer: Use ${CI_SERVER_URL} for self-hosted GitLab, or https://gitlab.com for GitLab.com.

Example Pipeline

See examples/example-pipeline.gitlab-ci.yml for a complete pipeline example.

Troubleshooting

OIDC Token Not Available

Ensure your job has id_tokens configured:

my-job:
  id_tokens:
    STELLAOPS_OIDC_TOKEN:
      aud: sigstore

Permission Denied

Check that:

1. The project has OIDC enabled (Settings > CI/CD > Token Access)
2. Protected branch/tag settings if using protected pipelines

Verification Fails

Common issues:

• Identity pattern doesn't match (check ref_type and ref)
• Wrong issuer (use ${CI_SERVER_URL} for self-hosted)
• Signature was created by different branch/tag

Resources

• Keyless Signing Guide
• Identity Constraints
• GitLab OIDC Documentation