Enforce policies

Block non-compliant artifacts from deploying by enforcing policies in CI/CD pipelines, via the API, or with Kubernetes admission controllers.

Environment policies define what an artifact needs to be compliant. Policy enforcement gates check artifacts against those requirements and block deployments when they fall short.

You can enforce policies:

• As a CI/CD pipeline step that fails the build on non-compliance
• Through the Kosli API for custom tooling
• Via a Kubernetes admission controller that rejects non-compliant pods

All methods use the same assertion: checking an artifact’s fingerprint against an environment, specific policies, or a flow template.

Assertion scopes

kosli assert artifact (and its API equivalent) supports three assertion modes:

Mode	CLI flag	When to use
Environment	--environment	Check all policies attached to the target environment. The most common choice for deployment gates.
Specific policies	--policy	Check one or more named policies, regardless of environment attachment. Useful for promotion gates between stages.
Flow templates	(no scope flag)	Check against the template files of the flows the artifact appears in.

--environment and --policy are mutually exclusive.

--flow can be combined with any mode to narrow the lookup to a specific flow. Without --flow, all flows containing the artifact (by fingerprint) are considered.

See kosli assert artifact for the full flag reference.

Enforce in CI/CD pipelines

Add kosli assert artifact as a step before your deployment step. If the artifact is non-compliant, the command exits with a non-zero status and the pipeline fails.

Assert against an environment

Check all policies attached to the target environment:

GitHub Actions

- name: Assert artifact compliance
  env:
    KOSLI_API_TOKEN: ${{ secrets.KOSLI_API_TOKEN }}
    KOSLI_ORG: my-org
  run: |
    kosli assert artifact ${{ env.IMAGE }} \
      --artifact-type oci \
      --environment production

GitLab CI

assert-compliance:
  stage: deploy
  script:
    - kosli assert artifact $IMAGE \
        --artifact-type oci \
        --environment production
  variables:
    KOSLI_API_TOKEN: $KOSLI_API_TOKEN
    KOSLI_ORG: my-org

Assert against specific policies

Check one or more named policies directly. This is useful when gating a promotion between stages or checking policies that are not attached to an environment:

kosli assert artifact $IMAGE \
  --artifact-type oci \
  --policy has-tests,has-review

Use --dry-run to test assertions without sending data to Kosli. The CLI prints the compliance result but always exits with code 0.

Enforce via the API

For custom deployment tooling or non-CI contexts, call the assert endpoint directly:

EU

curl -s \
  -H "Authorization: Bearer $KOSLI_API_TOKEN" \
  "https://app.kosli.com/api/v2/asserts/my-org/fingerprint/$SHA256?environment_name=production"

US

curl -s \
  -H "Authorization: Bearer $KOSLI_API_TOKEN" \
  "https://app.us.kosli.com/api/v2/asserts/my-org/fingerprint/$SHA256?environment_name=production"

The response includes:

• compliant — true or false
• policy_evaluations — detailed results per policy (when asserting against an environment)
• compliance_status — per-attestation compliance breakdown

To assert against specific policies instead of an environment:

EU

curl -s \
  -H "Authorization: Bearer $KOSLI_API_TOKEN" \
  "https://app.kosli.com/api/v2/asserts/my-org/fingerprint/$SHA256?policy_name=has-tests&policy_name=has-review"

US

curl -s \
  -H "Authorization: Bearer $KOSLI_API_TOKEN" \
  "https://app.us.kosli.com/api/v2/asserts/my-org/fingerprint/$SHA256?policy_name=has-tests&policy_name=has-review"

See the Assert artifact API reference for the full response schema. You can also try it out directly in the API playground on that page.

Enforce with a Kubernetes admission controller

A Kubernetes validating admission webhook can call the Kosli assert API when a pod is created and reject pods whose images are non-compliant.

The flow is:

1. Pod creation triggers the webhook

   Kubernetes calls your admission webhook before scheduling the pod.

2. Webhook extracts the image fingerprint

   The webhook reads the container image reference from the pod spec and resolves its SHA256 digest.

3. Webhook calls the Kosli assert API

   The webhook sends a request to the assert endpoint with the fingerprint and the target environment name.

4. Webhook returns allow or deny

   If compliant is true, the pod is admitted. If false, the webhook rejects the pod with a message explaining which policy requirements were not met.

The Kosli K8S Reporter reports what is running in your Kubernetes environments to Kosli. Pair it with an admission controller to both enforce and monitor compliance.

What happens on failure

CLI: A non-compliant artifact causes kosli assert artifact to exit with a non-zero code. CI/CD pipelines treat this as a failed step and stop the deployment. Use --output json to get machine-readable compliance details.

API: The response body returns compliant: false with a compliance_status object describing which attestations are missing or non-compliant, and policy_evaluations listing per-policy results.