# aflock-ai/cilock-action reference

Source: https://www.testifysec.com/docs/cilock/reference/github-action/

Source of truth: cilock-action/action.yml.

> Source of truth: [`cilock-action/action.yml`](https://github.com/aflock-ai/cilock-action/blob/main/action.yml).

 

The CI/lock GitHub Action wraps a command (or another GitHub Action) and produces signed attestations. It downloads its own variant of the `cilock` binary at runtime from the cilock-action releases.

 

```yaml
- uses: aflock-ai/cilock-action@d39bb9b17e392520f9e7eef17cf355c027a5c283 # v1.0.4
  with:
    step: build
    command: "go build -o myapp ./cmd/myapp"
    platform-url: ${{ vars.CILOCK_PLATFORM_URL }}   # your administrator-approved origin
```

 

**Name the destination.** With `enable-archivista` at its default (`true`), the action signs through the Fulcio derived from `platform-url` and uploads the evidence to that platform's Archivista. If you omit `platform-url`, both default to the hosted platform, `https://platform.testifysec.com`. Set it explicitly to the origin your administrator approved for this repository: the hosted platform, or your private or self-hosted deployment, with the tenant and product already set up there. See the [GitHub Actions tutorial](https://www.testifysec.com/docs/cilock/tutorials/github-actions-pipeline) for a preflight step that refuses to run without it.

 

**Release pinned in these docs:** [`v1.0.4`](https://github.com/aflock-ai/cilock-action/releases/tag/v1.0.4), commit `d39bb9b17e392520f9e7eef17cf355c027a5c283`, the release every recipe on this site was checked against. It bundles a CI/lock built from rookery `main` with `govulncheck`, `inclusion-proof`, `secretscan`, `slsa`, and the [PR #153 atomic-rename trace fix](https://github.com/aflock-ai/rookery/pull/153). It is not the newest release: GitHub lists [`v3.0.8`](https://github.com/aflock-ai/cilock-action/releases/tag/v3.0.8) (2026-06-10, commit `f3cf4e0487df980ee6aa3734229b4d2e9fd27a4d`), whose `platform-url` and `enable-archivista` defaults are the ones described on this page. Read a release's notes before moving a pipeline to it, then pin its commit SHA with the tag in a comment — never a moving tag or major-version ref, which can be re-pointed after you reviewed the workflow.

 

### What v1.0.4 evidence cannot do

 

v1.0.4 was built from an older rookery, and its evidence does not pass every verification these docs teach:

 

- **It records `command-run/v0.1`.** The policies in these docs require `https://aflock.ai/attestations/command-run/v0.2`, and verification refuses a v1.0.4 envelope against them (`missing required attestation .../command-run/v0.2`). A policy for v1.0.4 evidence has to name `command-run/v0.1`.
 - **Its products and materials carry no file list.** They appear only as Merkle `tree:` subjects, so `cilock verify -f <artifact>` and an `artifactsFrom` chain cannot pass on its evidence.
 - **`cilock-args` is mostly dropped.** It applies only the `--attestor-secretscan-*` flags. `--attestor-product-include-glob`, `--trace`, `--capture-mode`, `--require-zero-drops` and `--material-manifest` are silently ignored, and so is the `product-include-glob` input.
 - **An empty `platform-url` means the hosted platform.** `platform-url: ${{ vars.X }}` with `X` unset signs and uploads to `https://platform.testifysec.com`.

 

For a step that needs artifact (`-f`) or cross-step (`artifactsFrom`) verification, run the plain CLI (`cilock run`) until a release built from current source is published. The action's current source records `command-run/v0.2` and inline file lists. It applies the product globs, and it refuses `cilock-args`, an empty `platform-url` and the other inputs it would drop. That source is not released yet, so the pin above stays v1.0.4.

 

## Multi-step chain via `step` names

 

CI/lock's policy language lets you declare relationships between attested steps. By giving each step a distinct name and declaring `artifactsFrom` in the verification policy, the verifier enforces that step N's materials match step N-1's products byte-for-byte. This is how CI/lock's own release pipeline chains `vendor-cilock-deps` → `release-build` — see [Verify the `cilock` binary](https://www.testifysec.com/docs/cilock/getting-started/verify-the-cilock-binary).

 

v1.0.4 evidence cannot pass that check (see above), so run chained steps with the plain CLI in the same workflow. Install `cilock` on `PATH` first, outside the checkout, as the [release promotion gate](https://www.testifysec.com/docs/cilock/tutorials/release-promotion-gate#step-2-the-build-workflow-produces-evidence) does. `--material-manifest` keeps the file inventory the comparison reads, and the outfiles go under `$RUNNER_TEMP` so one step's evidence is not an input of the next:

 

```yaml
# Step 1 — vendor
- name: vendor-deps
  run: |
    cilock run --step vendor-deps --material-manifest \
      -o "$RUNNER_TEMP/vendor.attestation.json" \
      -- go mod vendor

# Step 2 — build; the policy chains app-build to vendor-deps
- name: app-build
  run: |
    cilock run --step app-build --material-manifest --trace \
      -o "$RUNNER_TEMP/build.attestation.json" \
      -- go build -mod=vendor -o app ./cmd/app
```

 

`--trace` records network egress and file operations for the hermetic Rego gates.

 

## Required permissions

 

For keyless Sigstore signing (the default), the workflow needs:

 

```yaml
permissions:
  id-token: write   # for OIDC token to Fulcio
  contents: read    # standard checkout
```

 

Add `packages: write` if you push container images, etc.

 

## Inputs

 

### Core

 

One of `command` or `action-ref` is required.

 

| Input | Default | Description |
| --- | --- | --- |
| `step` | (required) | Step name for the attestation. |
| `command` | (none) | Shell command to run, under `sh -c`. |
| `argv` | (none) | Program to run with no shell, one argument per line, the program first. The recorded command is exactly this argv, so attestors that check the program (`oci` for `docker push` or `crane`) and policies see it. Use instead of `command`. |
| `action-ref` | (none) | GitHub Action to wrap (`owner/repo@ref` or `docker://image`). |
| `action-inputs` | (none) | JSON map of inputs to pass to the wrapped action. |
| `action-env` | (none) | Additional env vars for the wrapped action (`KEY=VALUE` per line). |

 

### Binary

 

| Input | Default | Description |
| --- | --- | --- |
| `version` | the release the action commit was mirrored from | Leave it unset to run the binary the pinned commit names: a release commit carries the sha256 of its binaries (`shim/release.json`), so a tag, the major alias or a commit SHA runs exactly that release's verified bytes. Set `vX.Y.Z` to run a different release, checked against its published `.sha256`, or `latest`. Current source; through v4.6.2 a commit SHA or alias downloaded the latest GitHub release. |
| `cilock-binary-url` | (none) | URL of a pre-built `cilock-action` binary, not the `cilock` CLI. The shim runs it with no arguments and it reads the `INPUT_*` variables itself. No checksum is checked, so you own its integrity. |
| `cilock-args` | (none) | v1.0.4 applies only the `--attestor-secretscan-*` flags and silently drops the rest. Current source refuses the input. Use the dedicated inputs instead. |

 

### Attestation

 

| Input | Default | Description |
| --- | --- | --- |
| `attestations` | `environment git github` | Space-separated attestor list (the shim translates to the comma-separated form the `cilock` CLI expects). v1.0.4 reads `environment,git` as one unknown attestor; current source also accepts commas. |
| `outfile` | (none) | Output file for signed envelope. |
| `workingdir` | (none) | Working directory. |
| `trace` | `false` | Enable command tracing. |
| `hashes` | `sha256` | Hash algorithms. |

 

### TestifySec platform

 

| Input | Default | Description |
| --- | --- | --- |
| `platform-url` | `https://platform.testifysec.com` | All service URLs are derived from this, including where evidence is uploaded. Set it explicitly to your administrator-approved origin; the default sends evidence to the hosted platform. |

 

### Archivista

 

Derived from `platform-url` if not explicitly set.

 

| Input | Default | Description |
| --- | --- | --- |
| `enable-archivista` | `true` | Store attestations in Archivista. |
| `archivista-server` | derived from `platform-url` | Archivista server URL. |

 

### Sigstore / Fulcio

 

Derived from `platform-url` if not explicitly set.

 

| Input | Default | Description |
| --- | --- | --- |
| `enable-sigstore` | `true` | Enable Sigstore/Fulcio signing. |
| `fulcio-url` | derived from `platform-url` | Fulcio server URL. |
| `fulcio-oidc-client-id` | `sigstore` | Fulcio OIDC client ID. |
| `fulcio-oidc-issuer` | `https://token.actions.githubusercontent.com` | Fulcio OIDC issuer URL. |
| `fulcio-use-http` | `true` | Use HTTP/REST API for Fulcio (works behind any reverse proxy). |

 

### File signer

 

| Input | Default | Description |
| --- | --- | --- |
| `key` | (none) | Path to signing key. |
| `certificate` | (none) | Path to signing certificate. |
| `intermediates` | (none) | Comma-separated paths to intermediate certificates. |

 

### KMS signer

 

The key reference's scheme picks the provider. The Action links the AWS KMS provider only, so a `gcpkms://`, `azurekms://` or `hashivault://` reference fails the step before the wrapped command runs. AWS credentials come from the AWS SDK default chain: run [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) with GitHub OIDC and an IAM role allowed `kms:Sign`, `kms:GetPublicKey` and `kms:DescribeKey` on the key. The Action reads no AWS secret itself, and `AWS_ENDPOINT_URL` (or `AWS_ENDPOINT_URL_KMS`) points it at a VPC endpoint or LocalStack. With `enable-sigstore` left `true` the envelope carries a Fulcio signature as well; set it to `false` to sign with the KMS key alone. The policy functionary is the key's public key (`aws kms get-public-key`, as PEM).

 

| Input | Default | Description |
| --- | --- | --- |
| `kms-ref` | (none) | Key reference, e.g. `awskms:///alias/my-key` or `awskms:///arn:aws:kms:…:key/…`. |
| `kms-aws-profile` | (none) | AWS shared-config profile. Empty uses the SDK default chain. |

 

### Timestamps

 

| Input | Default | Description |
| --- | --- | --- |
| `timestamp-servers` | derived from `platform-url` | Space-separated TSA URLs. |
| `timestamp-allow-http` | `false` | Allow an `http://` TSA on a public host (DigiCert's `http://timestamp.digicert.com` answers RFC 3161 on HTTP only). Without it such a URL is refused before the command runs; local and private hosts may use HTTP either way. |

 

TSA URLs use HTTPS by default. `timestamp-allow-http: "true"` loosens the transport and nothing else. An RFC 3161 token is signed by the TSA, and the Action checks that signature and that the token answers this request's digest and nonce, so an attacker on the network can block a timestamp but cannot forge or alter one. The digest being timestamped does travel in the clear. The CLI flag is `--timestamp-allow-http`; on GitLab set `CILOCK_TIMESTAMP_ALLOW_HTTP=true`.

 

```yaml
- uses: testifysec/cilock-action@v1
  with:
    step: build
    command: make build
    timestamp-servers: http://timestamp.digicert.com
    timestamp-allow-http: "true"
```

 

### Environment filtering

 

| Input | Default | Description |
| --- | --- | --- |
| `env-add-sensitive-key` | (none) | Comma-separated additional sensitive env var keys. |
| `env-filter-sensitive-vars` | `false` | Filter (remove) sensitive vars instead of obfuscating. |

 

### Material / Product

 

| Input | Default | Description |
| --- | --- | --- |
| `product-include-glob` | `*` | Glob for product file inclusion. |
| `product-exclude-glob` | (none) | Glob for product file exclusion. |

 

### Declared but not supported

 

The Action signs with Fulcio, a key file or AWS KMS, and it builds no binary. `action.yml` still declares the inputs below, so a value reaches the Action and is refused with an error naming the input. Releases before the refusal parsed them and silently ignored them.

 

| Input | Use instead |
| --- | --- |
| `kms-gcp-credentials-file` | The `cilock` CLI with a GCP KMS signer. |
| `vault-url`, `vault-token` | The `cilock` CLI with a Vault signer. |
| `attestor-sbom-export`, `attestor-slsa-export` (`true`) | The `cilock` CLI. Their `false` default is accepted. |
| `builder-manifest`, `builder-preset` | Build a `cilock-action` binary with [rookery-builder](https://www.testifysec.com/docs/cilock/ecosystem/rookery) and pass `cilock-binary-url`. |

 

## Outputs

 

| Output | Description |
| --- | --- |
| `git_oid` | GitOID of the stored attestation. |
| `attestation_file` | Path to the attestation output. |

 

## Runtime

 

```yaml
runs:
  using: "node20"
  main: "shim/index.js"
```

 

The `shim/index.js` Node entry point downloads the `cilock-action` binary the release fan-out built and verified, from `https://cilock.dev/dl/<tag>/cilock_action-<version>-<os>-<arch>.tar.gz`, checks it against the sha256 the action commit carries, and runs it with no arguments; the binary reads the `INPUT_*` variables itself. Runners need egress to `cilock.dev`. An unreleased copy of the action (no `shim/release.json`) needs `version: vX.Y.Z`. This is current source; v4.6.2 and earlier download from the action's GitHub releases.

 

## SLSA Build L3: the provenance workflow

 

Availability — read before you run this

The verifier half ships: `cilock verify --slsa-level` is in cilock v4.6.0 and later. The builder half ships too: `provenance.yml` is in cilock-action release v4.6.2, byte for byte the file on `main`, so pin a commit that contains it. Even so, the [standards guidance](https://www.testifysec.com/docs/cilock/reference/standards-guidance) and the [support matrix](https://www.testifysec.com/docs/concepts/support-matrix#sm-planned-isolated-provenance) still list SLSA Build L3 as planned, because the matrix does not yet count this mode as available. Treat this section as early access, not a supported level.

 

When cilock runs inside your build job, the provenance it signs can reach SLSA Build L2 at most. The job's own steps could forge it. For L3, add a second job. It calls the reusable `provenance.yml` workflow, runs none of your code, and signs SLSA v1 provenance with its own Fulcio identity:

 

```yaml
  provenance:
    needs: build
    permissions: { id-token: write }
    uses: aflock-ai/cilock-action/.github/workflows/provenance.yml@<40-hex commit>
    with: { subjects: "${{ needs.build.outputs.subjects }}" }
```

 

- **Pin by commit, never by tag.** The verifier requires the certificate's Build Signer URI to name the pinned commit, so a tag pin is refused.
 - **`subjects`** is one `<name>=sha256:<hex>` per line. Your build job outputs it, for example with `echo "subjects=app=sha256:$(sha256sum dist/app | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"`. The build job must also run cilock in the same workflow run: a subject is accepted only if that run's build collection carries it.
 - **Triggers:** the workflow signs only for `push`, `release` and `workflow_dispatch`. Any other event, fork pull requests and `pull_request_target` included, fails the job.
 - **Signer:** the platform's Fulcio and timestamp authority by default (`platform-url`). Set `public-sigstore: true` to use public Sigstore instead.

 

Verify with the built-in L3 policy. There is no `-p`:

 

```bash
cilock verify ./dist/app --slsa-level 3 \
  --slsa-builder-digest <the same commit> --slsa-source-repo <owner>/<repo> \
  -a provenance.json -a build.json --vsa-outfile vsa.json
```

 

`--slsa-level 3` exits 0 only if all of these hold:

 

- the provenance's signing certificate names `provenance.yml` at that commit, a GitHub-hosted runner, a writer-only trigger, and your repository;
 - builder.id, repository, commit and run in the statement equal that certificate's extensions;
 - `buildType` and `externalParameters` are what `provenance.yml` writes;
 - the artifact is among the subjects, and a build collection from the same run, repository and commit carries it.

 

`--format json` lists each requirement that failed. The VSA states `SLSA_BUILD_LEVEL_3` only on a pass. Add `--slsa-roots public-sigstore` with `--slsa-public-sigstore-ca-roots` and `--slsa-public-sigstore-timestamp-servers` to accept public Sigstore signatures.

 

## Worked examples

 

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

 

- Wrapping another GitHub Action (e.g. `docker/build-push-action`)
 - Wrapping a shell command
 - Multi-step pipeline with downstream verification

 

The full end-to-end walkthrough lives in the [GitHub Actions tutorial](https://www.testifysec.com/docs/cilock/tutorials/github-actions-pipeline).

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