907783f625
- Implement `SbomVexOrderingDeterminismProperties` for testing component list and vulnerability metadata hash consistency. - Create `UnicodeNormalizationDeterminismProperties` to validate NFC normalization and Unicode string handling. - Add project file for `StellaOps.Testing.Determinism.Properties` with necessary dependencies. - Introduce CI/CD template validation tests including YAML syntax checks and documentation content verification. - Create validation script for CI/CD templates ensuring all required files and structures are present.
127 lines
3.7 KiB
Markdown
127 lines
3.7 KiB
Markdown
# 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)
|