Environment Policy

Reference for the YAML policy files used to define compliance requirements for Kosli environments.

An environment policy is a YAML file that declares compliance requirements for artifacts running in a Kosli environment. You pass the file to kosli create policy to create or update a policy. For concepts, workflow, and enforcement, see Environment Policies.

Prefer to build a policy interactively? Use the Policy builder to assemble a valid policy file in your browser and copy the YAML.

Specification

_schema · string · required

Version identifier and JSON Schema URL for the policy format. The final path segment must match /v{n} where n is a supported major version. Currently only v1 is supported.

# yaml-language-server: $schema=https://docs.kosli.com/schemas/policy/v1.json
_schema: https://docs.kosli.com/schemas/policy/v1

artifacts · object

Rules applied to artifacts in an environment snapshot. Omitted keys use server defaults.

Show artifacts properties

artifacts.provenance · object

Requires artifacts to have provenance (i.e., be part of a Kosli flow).

Show provenance properties

artifacts.provenance.required · boolean · default: "false"

When true, every artifact in the snapshot must have provenance.

artifacts.provenance.exceptions · array · default: "[]"

List of conditions under which the provenance requirement is waived. Each element is an object with a single if key containing a policy expression.

exceptions:
  - if: ${{ matches(artifact.name, "^datadog:.*") }}

artifacts.trail-compliance · object

Requires artifacts to belong to a compliant trail in their flow.

Show trail-compliance properties

artifacts.trail-compliance.required · boolean · default: "false"

When true, every artifact must be part of a compliant trail.

artifacts.trail-compliance.exceptions · array · default: "[]"

List of conditions under which the trail-compliance requirement is waived. Same structure as provenance.exceptions.

artifacts.attestations · array · default: "[]"

List of attestations every artifact must have. Each element is a required-attestation rule.

A rule is evaluated against the newest attestation whose name and type match the rule, including override attestations — an override supersedes the status of the attestation it overrides. Overriding a non-compliant attestation can therefore bring an environment back to compliant, and overriding a compliant one down to non-compliant makes the environment non-compliant.

Show attestation rule properties

artifacts.attestations[].type · string · required

The attestation type to require. Cannot be * when name is also *.

artifacts.attestations[].name · string · default: "*"

Attestation name to match. * matches any name. Cannot be * when type is also *.

artifacts.attestations[].if · string

A policy expression. When present, this attestation is only required when the expression evaluates to true.

Attestation types

Value	Description
generic	Generic attestation
junit	JUnit test results
snyk	Snyk security scan
pull_request	Pull request evidence
jira	Jira ticket reference
sonar	SonarQube analysis
*	Matches any built-in or custom type
custom:<name>	A custom attestation type (e.g., custom:coverage-metrics)

Policy expressions

Expressions are boolean conditions evaluated against flow and artifact context. They are wrapped in ${{ }} and can appear in if and exceptions[].if fields.

if: ${{ flow.tags.risk-level == "high" and matches(artifact.name, "^prod:.*") }}

Operators

Operator	Category	Example
==	Comparison	flow.name == "runner"
!=	Comparison	flow.tags.risk-level != "high"
<	Comparison	flow.tags.priority < 3
>	Comparison	flow.tags.priority > 1
<=	Comparison	flow.tags.risk-level <= 2
>=	Comparison	flow.tags.risk-level >= 2
and	Logical	flow.name == "a" and artifact.name == "b"
or	Logical	flow.name == "a" or flow.name == "b"
not	Logical	not flow.tags.risk-level == "high"
in	Membership	flow.name in ["runner", "saver"]

Parentheses control precedence: ${{ flow.name == 'prod' and (flow.tags.team == "a" or artifact.name == 'svc') }}.

Contexts

flow · object

Information about the Kosli flow the artifact belongs to.

Show flow properties

flow.name · string

Name of the flow.

flow.tags · object

Flow tags, accessed by key: flow.tags.risk-level, flow.tags.team. Keys containing dots are supported: flow.tags.key.with.dots.

artifact · object

Information about the artifact being evaluated.

Show artifact properties

artifact.name · string

Name of the artifact.

artifact.fingerprint · string

SHA256 fingerprint of the artifact.

Functions

Function	Description	Example
exists(arg)	Returns true if arg is not null.	${{ exists(flow) }}
matches(input, regex)	Returns true if input matches the regular expression.	${{ matches(artifact.name, "^datadog:.*") }}

Missing values

A value is missing when the context does not supply it. This is common rather than exceptional:

• flow is missing for any artifact reported without provenance.
• flow.tags.<key> is missing for a tag the flow does not have.

The comparison operators (==, !=, <, >, <=, >=), the membership operator in, and the functions exists() and matches() all evaluate to false when either operand is missing. A missing operand is not an error — the comparison is simply not satisfied.

To branch on whether a value is present at all, test it with exists() rather than relying on a comparison against it.

Constraints

• _schema is the only required field. All other fields are optional and use server defaults when omitted.
• An attestation rule must not have both name and type set to *.
• Expressions must evaluate to a boolean. An invalid expression causes a policy evaluation error.

Example

# yaml-language-server: $schema=https://docs.kosli.com/schemas/policy/v1.json
_schema: https://docs.kosli.com/schemas/policy/v1

artifacts:
  provenance:
    required: true
    exceptions:
      - if: ${{ matches(artifact.name, "^datadog:.*") }}

  trail-compliance:
    required: true

  attestations:
    - name: security-scan
      type: snyk
    - name: pull-request
      type: pull_request
      if: ${{ flow.tags.risk-level == "high" }}
    - name: coverage
      type: custom:coverage-metrics

Editor validation

The _schema URL resolves to a JSON Schema for the environment policy format. To enable inline validation and autocomplete in VS Code (requires the YAML extension) and other schema-aware editors, add a yaml-language-server directive:

# yaml-language-server: $schema=https://docs.kosli.com/schemas/policy/v1.json
_schema: https://docs.kosli.com/schemas/policy/v1

See also

• Policy builder — build a policy file interactively in the browser
• Environment Policies — concepts, workflow, and enforcement
• kosli create policy — create or update a policy
• kosli attach-policy — attach a policy to an environment
• kosli assert artifact — enforce policies on an artifact
• Terraform: kosli_policy — manage policies via Terraform