Skip to main content
View Markdown ↗

Copy this page

Select and copy the Markdown below, then paste it into your LLM.

On this page

aflock-ai/cilock-action reference

Source of truth: cilock-action/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.

- 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 for a preflight step that refuses to run without it.

Release pinned in these docs: 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. It is not the newest release: GitHub lists 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.

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

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

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.

InputDefaultDescription
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

InputDefaultDescription
versionthe release the action commit was mirrored fromLeave 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

InputDefaultDescription
attestationsenvironment git githubSpace-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.
tracefalseEnable command tracing.
hashessha256Hash algorithms.

TestifySec platform

InputDefaultDescription
platform-urlhttps://platform.testifysec.comAll 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.

InputDefaultDescription
enable-archivistatrueStore attestations in Archivista.
archivista-serverderived from platform-urlArchivista server URL.

Sigstore / Fulcio

Derived from platform-url if not explicitly set.

InputDefaultDescription
enable-sigstoretrueEnable Sigstore/Fulcio signing.
fulcio-urlderived from platform-urlFulcio server URL.
fulcio-oidc-client-idsigstoreFulcio OIDC client ID.
fulcio-oidc-issuerhttps://token.actions.githubusercontent.comFulcio OIDC issuer URL.
fulcio-use-httptrueUse HTTP/REST API for Fulcio (works behind any reverse proxy).

File signer

InputDefaultDescription
key(none)Path to signing key.
certificate(none)Path to signing certificate.
intermediates(none)Comma-separated paths to intermediate certificates.

KMS signer (AWS KMS)

The key reference's scheme picks the provider. The Action links the AWS KMS and Vault Transit providers, so a gcpkms:// or azurekms:// reference fails the step before the wrapped command runs. AWS credentials come from the AWS SDK default chain: run 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).

InputDefaultDescription
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.

Vault Transit signer

kms-ref: hashivault://<key> signs with a HashiCorp Vault Transit key; the private key never leaves Vault. A key the token cannot read fails the step before the wrapped command runs: the Action reads the key's public key while it builds the signer.

The Action has no Vault login of its own and takes no token input. Log in first with hashicorp/vault-action using method: jwt and exportToken: true: it exchanges the job's GitHub OIDC token for a Vault token and exports VAULT_TOKEN, which the signer reads. Bind the Vault JWT role to bound_audiences and to bound_claims on repository and job_workflow_ref, so only that workflow can sign, and give its policy update on transit/sign/<key>/sha2-256 and read on transit/keys/<key> only (with vault-transit-path set, replace transit with that mount). The signer always posts its SHA-256 digest to the hash-suffixed path, and Vault's exact-path grant on transit/sign/<key> does not cover it: signing would fail with 403. With enable-sigstore left true the envelope carries a Fulcio signature as well; set it to false to sign with the Vault key alone. Each run signs with one key version, the latest when the step starts, and the policy functionary is that version's public key (vault read transit/keys/<key>, the version's public_key). After a key rotation, add the new version's public key to the policy. The id-token: write permission the login needs also lets the Action authenticate to the platform, which then requires a product binding; with no platform product, set platform-binding: skip.

Signature format. Envelopes signed through hashivault:// by earlier cilock releases carried Vault's own wire string (vault:v1:...) as the signature, which no public key verifies, so only a round trip to Vault's verify endpoint could check them. Signing now stores the raw DER signature, and cilock verify with the key's public key as functionary passes offline. Envelopes already signed in the old form still verify, through Vault. The break runs the other way: a verifier built before this change that checks a new envelope through Vault's verify endpoint sends the raw signature unwrapped and Vault rejects it. Upgrade verifiers that use the Vault round trip before the signers move to this release, or verify offline.

InputDefaultDescription
kms-ref(none)hashivault://<key>, the Transit key name.
vault-urlVAULT_ADDRVault address. Set without a hashivault:// kms-ref, it is refused.
vault-transit-pathtransitMount path of the Transit secrets engine. Set without a hashivault:// kms-ref, it is refused.
permissions:
  id-token: write   # the GitHub OIDC token vault-action exchanges
  contents: read
steps:
  - uses: hashicorp/vault-action@892a26828f195e65540a40b4768ae4571f51ebfc # v4.0.0
    with:
      url: https://vault.example.com:8200
      method: jwt
      role: cilock-signing
      jwtGithubAudience: https://vault.example.com
      exportToken: true
  - uses: aflock-ai/cilock-action@<40-hex commit>
    with:
      step: build
      command: mvn -B clean install
      kms-ref: hashivault://cilock-signing
      vault-url: https://vault.example.com:8200
      enable-sigstore: "false"
      platform-binding: skip   # only when not attesting to a platform product

Timestamps

InputDefaultDescription
timestamp-serversderived from platform-urlSpace-separated TSA URLs.
timestamp-allow-httpfalseAllow 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.

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

Environment filtering

InputDefaultDescription
env-add-sensitive-key(none)Comma-separated additional sensitive env var keys.
env-filter-sensitive-varsfalseFilter (remove) sensitive vars instead of obfuscating.

Material / Product

InputDefaultDescription
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, AWS KMS or Vault Transit, 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 and never its value. Releases before the refusal parsed them and silently ignored them.

InputUse instead
vault-tokenhashicorp/vault-action with exportToken: true; the signer reads VAULT_TOKEN.
kms-gcp-credentials-fileThe cilock CLI with a GCP KMS signer.
attestor-sbom-export, attestor-slsa-export (true)The cilock CLI. Their false default is accepted.
builder-manifest, builder-presetBuild a cilock-action binary with rookery-builder and pass cilock-binary-url.

Outputs

OutputDescription
git_oidGitOID of the stored attestation.
attestation_filePath to the attestation output.

Runtime

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 and the support matrix 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:

  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:

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/:

  • 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.

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