Environment Policy - Kosli Documentation

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

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

object

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

Show artifacts properties

object

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

Show provenance properties

boolean

default:"false"

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

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:.*") }}

object

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

Show trail-compliance properties

boolean

default:"false"

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

array

default:"[]"

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

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

string

required

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

string

default:"*"

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

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

object

Information about the Kosli flow the artifact belongs to.

Show flow properties

string

Name of the flow.

object

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

object

Information about the artifact being evaluated.

Show artifact properties

string

Name of the artifact.

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

​Specification

​Attestation types

​Policy expressions

​Operators

​Contexts

​Functions

​Missing values

​Constraints

​Example

​Editor validation

​See also

Specification

Attestation types

Policy expressions

Operators

Contexts

Functions

Missing values

Constraints

Example

Editor validation

See also