docs: add working with controls tutorial by pbeckham · Pull Request #154 · kosli-dev/docs

pbeckham · 2026-04-16T09:57:59Z

❗️
This is a a proposed feature. Presented as a tutorial in order to get feedback on the design and feature set before starting development.
It is not a feature in Kosli - yet...

Summary

Adds tutorials/working_with_controls.mdx — a tutorial covering how to define controls in Kosli, record decisions against them, reference them in environment policies, and view compliance across deployments.
Updates config/navigation.json to include the new page under a new "Controls" group in the Tutorials section.

Closes kosli-dev/server#5355

mintlify · 2026-04-16T09:58:04Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Apr 16, 2026, 9:58 AM

…se, and dark controls paragraph

mbevc1 · 2026-04-16T13:55:54Z

Was this released yet? I cannot see this in Kosli 🤔

pbeckham · 2026-04-16T14:16:36Z

Was this released yet? I cannot see this in Kosli 🤔

No this is a proposed feature. We are making this documentation ahead of development to facilitate discussions and get early feedback before we build it.

mbevc1 · 2026-04-16T14:24:08Z

Okay, I assume we're not releasing this to docs yet then? I think it might confuse our customers.

…fix tab order

…ple to use kosli evaluate

tooky · 2026-04-17T12:21:07Z

Perhaps we can make this a "draft" PR?, just to prevent it being merged :)

pbeckham · 2026-04-21T10:18:32Z

+
+### Deployments
+
+The Deployments tab shows where artifacts with decisions against this control have been deployed, with compliant/non-compliant status per deployment, filterable by repository, flow, and environment.


How do we get the correct list of environments that this Control should apply to for deployments and Coverage views?

Potential options

Default filter to environments that have had a decision recorded for this Control (ever, in time range?).

Easy first attempt

Need to ensure this gives a realistic coverage (decision recorded ever would be consistent, but how do you remove from filter)

Default filter to environments that have Control mentioned in environment policy.

Add explicit mappings on Controls to environments they apply to that Customers should maintain.

pbeckham · 2026-04-21T11:52:15Z

+| `--attachments` | Optional evidence file(s) to attach (e.g. an evaluation report, a REGO policy output). |
+| `--user-data` | Optional path to a JSON file containing additional structured data to attach to the attestation. |
+
+The decision attestation goes on a trail, like any other attestation. It affects trail compliance: a `--compliant false` decision makes the trail non-compliant. There are no restrictions on which flow or trail a decision can be recorded on — place it wherever makes sense in your process, typically at the point where the decision is actually being made (e.g. during a release preparation or promotion step).


Should there be any distinctions around how a decision attestation appears on a trail.

Can it be given a named slot?

…tutorial Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…onment Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…policy/v1 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…identifier Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: add working with controls tutorial

340ad1d

pbeckham requested a review from a team as a code owner April 16, 2026 09:58

mintlify Bot deployed to staging April 16, 2026 09:58 View deployment

pbeckham commented Apr 16, 2026

View reviewed changes

docs: address review comments on working with controls tutorial

c05edc7

mintlify Bot deployed to staging April 16, 2026 10:17 View deployment

docs: add mock screenshots for controls compliance tutorial

eb257bc

mintlify Bot deployed to staging April 16, 2026 10:29 View deployment

docs: add controls listing screenshot with versioning to tutorial

c1e47f3

mintlify Bot deployed to staging April 16, 2026 10:35 View deployment

pbeckham commented Apr 16, 2026

View reviewed changes

Comment thread tutorials/working_with_controls.mdx Outdated

Comment thread tutorials/working_with_controls.mdx Outdated

Comment thread tutorials/working_with_controls.mdx Outdated

docs: fix policy YAML to use controls key and correct schema URL

39ab9b0

mintlify Bot deployed to staging April 16, 2026 10:52 View deployment

docs: add catalog-level coverage status indicators to controls tutorial

df0f3c6

mintlify Bot deployed to staging April 16, 2026 10:57 View deployment

pbeckham commented Apr 16, 2026

View reviewed changes

Comment thread images/tutorials/controls-list.png

Comment thread tutorials/working_with_controls.mdx Outdated

Comment thread tutorials/working_with_controls.mdx Outdated

Comment thread images/tutorials/controls-compliance-coverage.png

docs: address PR feedback on screenshots and policy enforcement wording

3558415

mintlify Bot deployed to staging April 16, 2026 13:41 View deployment

pbeckham commented Apr 16, 2026

View reviewed changes

Comment thread tutorials/working_with_controls.mdx Outdated

Comment thread tutorials/working_with_controls.mdx Outdated

docs: remove remaining evidenced/unevidenced language from tutorial body

e3ccac3

mintlify Bot deployed to staging April 16, 2026 13:48 View deployment

docs: remove admission controller mention, automated evaluation promi…

75e25fd

…se, and dark controls paragraph

mintlify Bot deployed to staging April 16, 2026 13:51 View deployment

pbeckham commented Apr 16, 2026

View reviewed changes

docs: add decisions tab with screenshot, mention control versioning, …

84c24fa

…fix tab order

mintlify Bot deployed to staging April 16, 2026 15:16 View deployment

docs: remove CLI version requirement from prerequisites

714eb7a

mintlify Bot deployed to staging April 16, 2026 15:34 View deployment

docs: use repo instead of flow in coverage view; update evidence exam…

7600293

…ple to use kosli evaluate

mintlify Bot deployed to staging April 16, 2026 15:47 View deployment

tooky marked this pull request as draft April 17, 2026 12:21

pbeckham commented Apr 21, 2026

View reviewed changes

dangrondahl reviewed Apr 21, 2026

View reviewed changes

Comment thread tutorials/working_with_controls.mdx Outdated

dangrondahl reviewed Apr 21, 2026

View reviewed changes

Comment thread tutorials/working_with_controls.mdx Outdated

Comment thread tutorials/working_with_controls.mdx Outdated

dangrondahl reviewed Apr 21, 2026

View reviewed changes

Comment thread tutorials/working_with_controls.mdx Outdated

Comment thread tutorials/working_with_controls.mdx Outdated

docs: add in-development banner to controls tutorial

ffb2b6b

mintlify Bot deployed to staging April 21, 2026 13:41 View deployment

pbeckham and others added 2 commits April 23, 2026 14:27

docs: add kosli assert control (PEP) and PDP/PEP framing to controls …

f687c02

…tutorial Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: add artifact scoping to decision and assert control commands

7e35a78

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mintlify Bot deployed to staging April 23, 2026 13:56 View deployment

pbeckham and others added 2 commits April 23, 2026 16:00

docs: add end-to-end pipeline flow sequence diagram to controls tutorial

3d041f6

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: replace kosli assert control with kosli assert artifact --envir…

3a656f0

…onment Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mintlify Bot deployed to staging April 23, 2026 15:04 View deployment

pbeckham and others added 4 commits April 23, 2026 16:09

docs: change PDP/PEP diagram notes to Note right of P

7c8c431

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: update environment policy schema URL to docs.kosli.com/schemas/…

b836fb7

…policy/v1 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: rename control code to control identifier and --code flag to --…

7ec36e2

…identifier Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs: clarify Active and Stale control status thresholds to 28 days

b35b360

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mintlify Bot deployed to staging April 23, 2026 15:19 View deployment


		### Deployments

		The Deployments tab shows where artifacts with decisions against this control have been deployed, with compliant/non-compliant status per deployment, filterable by repository, flow, and environment.

Conversation

pbeckham commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

mintlify Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mbevc1 commented Apr 16, 2026

Uh oh!

pbeckham commented Apr 16, 2026

Uh oh!

mbevc1 commented Apr 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tooky commented Apr 17, 2026

Uh oh!

pbeckham Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

pbeckham Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pbeckham commented Apr 16, 2026 •

edited

Loading

mintlify Bot commented Apr 16, 2026 •

edited

Loading