# 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`:

```yaml
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:

```yaml
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](../../docs/modules/signer/guides/keyless-signing.md)
- [Identity Constraints](../../docs/guides/identity-constraints.md)
- [GitLab OIDC Documentation](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html)