# CI/lock GitLab CI template reference

Source: https://www.testifysec.com/docs/cilock/reference/gitlab-component/

Source of truth: cilock-action/gitlab/cilock.gitlab-ci.yml, cilock-action/gitlab/cilock-platform.gitlab-ci.yml and cilock-action/gitlab/README.md.

> Source of truth: [`cilock-action/gitlab/cilock.gitlab-ci.yml`](https://github.com/aflock-ai/cilock-action/blob/main/gitlab/cilock.gitlab-ci.yml), [`cilock-action/gitlab/cilock-platform.gitlab-ci.yml`](https://github.com/aflock-ai/cilock-action/blob/main/gitlab/cilock-platform.gitlab-ci.yml) and [`cilock-action/gitlab/README.md`](https://github.com/aflock-ai/cilock-action/blob/main/gitlab/README.md).

 

CI/lock for GitLab CI ships as two reusable templates. Both define a `.cilock` hidden job to extend:

 

- `cilock.gitlab-ci.yml` downloads the `cilock-action` binary from a mirror you name and runs `CILOCK_COMMAND` under it. It is configured with `CILOCK_*` variables (this page, first).
 - `cilock-platform.gitlab-ci.yml` takes `spec: inputs:`, installs `cilock` from your platform, and signs and uploads with the job's own ID tokens. See [Platform template](https://www.testifysec.com/docs/cilock/reference/gitlab-component/#platform-template-cilock-platformgitlab-ciyml).

 

```yaml
include:
  - remote: 'https://raw.githubusercontent.com/aflock-ai/cilock-action/v4.6.2/gitlab/cilock.gitlab-ci.yml'

build:
  extends: .cilock
  variables:
    CILOCK_ACTION_BASE_URL: "https://mirror.example.internal/cilock-action"
    CILOCK_STEP: build
    CILOCK_COMMAND: "go build -o myapp ./cmd/myapp"
```

 

Pin the include to a tag. The older `v1` ref serves a previous template that downloads from a release path that does not exist.

 

## Variables

 

Defaults below match `cilock-action/gitlab/cilock.gitlab-ci.yml`. Variables set as `.cilock` job-level defaults take precedence over workflow-level `variables:` blocks (GitLab CI precedence rule), so override them in per-job `variables:` (or as project CI/CD variables) rather than at the top of the file.

 

| Variable | Default | Description |
| --- | --- | --- |
| `CILOCK_STEP` | (required) | Step name for the attestation. |
| `CILOCK_COMMAND` | (required) | Shell command to run. |
| `CILOCK_ACTION_BASE_URL` | (required, no default) | `https://` directory of release folders. The job stops before it runs without it. For an exact `CILOCK_VERSION` it first fetches `<version>/cilock_action-<ver>-<os>-<arch>.tar.gz` and its `.sha256`, the layout the release fan-out publishes under `https://cilock.dev/dl` (current source; releases from the fan-out that builds the action onward). It falls back to `<version>/cilock-action_<os>_<arch>.tar.gz` and `<version>/checksums.txt`, the layout of the GitHub releases under `https://github.com/aflock-ai/cilock-action/releases/download` (v4.6.2 and earlier), used when the fan-out archive is not on the mirror. |
| `CILOCK_VERSION` | `latest` | A release tag (`vX.Y.Z`, optional prerelease), refused before any download otherwise, or `latest`. `latest` reads the `latest` field of `<CILOCK_ACTION_BASE_URL>/manifest.json`, which a mirror of `https://cilock.dev/dl` carries; a mirror without one falls back to its `latest/` directory in the GitHub-release layout and warns, because releases from the fan-out onward do not update that directory. Pin a full release tag. |
| `CILOCK_ACTION_REF` | (none) | Run and attest a GitHub Action (`owner/repo@ref`) instead of `CILOCK_COMMAND`. No variable sets the action's inputs. |
| `CILOCK_ATTESTATIONS` | `environment git gitlab` | Space-separated attestor list (the `cilock-action` shim translates this to the comma-separated form `cilock` expects). |
| `CILOCK_ENABLE_ARCHIVISTA` | `true` | Store attestations in Archivista. |
| `CILOCK_PLATFORM_URL` | `https://platform.testifysec.com` | Platform origin. cilock-action derives Archivista (`/archivista`), Fulcio and the TSA (`/api/v1/timestamp`) from it, but this template sets `CILOCK_ARCHIVISTA_SERVER` and `CILOCK_TIMESTAMP_SERVERS` itself, so those two do not follow it unless you set them too. The template in current source no longer sets them (#13115); that change ships with the next cilock-action release, so a pinned `v4.6.2` include still needs both set. Set but empty is refused. |
| `CILOCK_PRODUCT` | (none) | Product to bind the evidence to. `CILOCK_PLATFORM_BINDING: skip` opts out of binding. |
| `CILOCK_ARCHIVISTA_SERVER` | `https://web.platform.testifysec.com` | Archivista server URL. |
| `CILOCK_TIMESTAMP_SERVERS` | `https://tsa.platform.testifysec.com/api/v1/timestamp` | RFC 3161 timestamp authority URLs, space-separated. This is the value the template sets. Set it to your platform's `<platform-url>/api/v1/timestamp` rather than relying on it. |
| `CILOCK_PRODUCT_INCLUDE_GLOB` | `*` | Glob for product file inclusion. `CILOCK_PRODUCT_EXCLUDE_GLOB` excludes. |
| `CILOCK_HASHES` | `sha256` | Hash algorithms. |
| `CILOCK_ENABLE_SIGSTORE` | `false` | Enable Sigstore/Fulcio signing. The template does not set it; cilock-action's GitLab parser defaults it to `false`. `CILOCK_FULCIO_URL`, `CILOCK_FULCIO_OIDC_ISSUER`, `CILOCK_FULCIO_OIDC_CLIENT_ID` (default `sigstore`) and `CILOCK_FULCIO_TOKEN` configure it. |
| `CILOCK_KEY` | (none) | Path to signing key (file signer). `CILOCK_CERTIFICATE` and `CILOCK_INTERMEDIATES` (comma-separated) add a certificate chain. |
| `CILOCK_KMS_REF` | (none) | Not supported. No release has applied it, or `CILOCK_KMS_AWS_PROFILE`, `CILOCK_KMS_GCP_CREDENTIALS_FILE`, `CILOCK_VAULT_URL` or `CILOCK_VAULT_TOKEN`: every release so far ignores them, and current source refuses each. Use the `cilock` CLI for KMS or Vault signing. |
| `CILOCK_OUTFILE` | (none) | Exact path the signed envelope is written to; no suffix or extension is added. Unset prints the envelope to the job log. |
| `CILOCK_WORKINGDIR` | (none) | Directory the command runs in. `CILOCK_GIT_ALLOW_SUBDIRECTORY: "true"` allows one below the repository root. |
| `CILOCK_SUBJECTS` | (none) | Extra subjects, one per line. |
| `CILOCK_TRACE` | `false` | Enable command tracing. |
| `CILOCK_SCRIPT_CAPTURE` | `content` | How much of an executed script to record: `off`, `identity` or `content`. |
| `CILOCK_ENV_FILTER_SENSITIVE_VARS`, `CILOCK_ENV_ADD_SENSITIVE_KEY` | (none) | Environment attestor filtering. |
| `CILOCK_INHERIT_CI_OIDC_CREDENTIALS` | `false` | Let the wrapped command or action inherit the CI OIDC token credentials. Off because a step holding them can obtain a signing certificate for the identity cilock signs with. |
| `CILOCK_ARGS` | (refused) | Not supported. cilock-action applies no raw cilock flags, so any value fails the job. Use the matching variable, or run the `cilock` CLI. |

 

## Outputs

 

The template produces a `cilock.env` dotenv artifact that downstream stages can pick up via `dependencies` / `needs`.

 

```yaml
artifacts:
  reports:
    dotenv: cilock.env
```

 

This is how subsequent stages (e.g. a verify stage) can reference the GitOID or attestation file produced by an earlier step.

 

## Differences from the GitHub Action

 

| Capability | GitHub Action | GitLab template |
| --- | --- | --- |
| Default attestations | `environment git github` | `environment git gitlab` |
| Default `enable-sigstore` | `true` | `false` |
| Configuration | Action `with:` inputs | `CILOCK_*` variables |
| Wrapping another tool | `action-ref:` input | `CILOCK_ACTION_REF`, with no variable for the action's inputs |
| OIDC | GitHub `id-token` permission | GitLab `id_tokens:` (`CI_JOB_JWT_V2` was removed in GitLab 17) |

 

## Platform template (`cilock-platform.gitlab-ci.yml`)

 

This template installs `cilock` itself, not `cilock-action`, from `<platform_url>/api/tools`, checks its sha256, and defines a `cilock` shell function that adds `--platform-url` to `run`, `attest`, `sign`, `verify`, `login`, `whoami` and `trust`. The `.cilock` job declares three ID tokens: `SIGSTORE_ID_TOKEN` (audience `sigstore`), `CILOCK_ARCHIVISTA_ID_TOKEN` (`<platform_url>/archivista`) and `CILOCK_LOGIN_ID_TOKEN` (`<platform_url>/login`). Jobs write plain `cilock` commands in `script:`.

 

```yaml
include:
  - remote: 'https://raw.githubusercontent.com/aflock-ai/cilock-action/v4.6.2/gitlab/cilock-platform.gitlab-ci.yml'
    inputs:
      platform_url: https://platform.example.com

build:
  extends: .cilock
  script:
    - cilock run --step build -- make
```

 

| Input | Default | Description |
| --- | --- | --- |
| `platform_url` | (required) | Platform origin the job signs against and uploads to. No trailing slash. |
| `cilock_sha256` | `""` | sha256 of the `cilock` binary to accept. Empty takes the hash the platform lists for the runner's architecture. |
| `image` | `curlimages/curl:8.10.1` | Job image. Needs `curl`, `sha256sum` and a POSIX shell. A job's own `image:` overrides it. |

 

A tenant admin first trusts the project: `cilock trust gitlab <group>/<project> --host <gitlab-host> --platform-url <platform_url>`. A job that defines its own `before_script` replaces the template's, so call the setup from it with `!reference [.cilock, before_script]`.

 

## Example pipelines

 

The template ships worked examples in [`examples/gitlab/`](https://github.com/aflock-ai/cilock-action/tree/main/examples/gitlab):

 

- `basic.gitlab-ci.yml`, minimum two-stage build + test
 - `pipeline.gitlab-ci.yml`, multi-step pipeline with file-based signing and a downstream verify stage

 

The full end-to-end walkthrough lives in the [GitLab CI tutorial](https://www.testifysec.com/docs/cilock/tutorials/gitlab-ci-pipeline).

Reference generated from the product documentation. Match commands and support details to your installed release.
