docs: refresh the querying Kosli tutorial against current cyber-dojo data - #413
Conversation
…data cyber-dojo renamed its flows to *-ci, so the tutorial's creator commands failed with "Flow named 'creator' does not exist". Follow one current commit (creator 99d7b74) through search, list, get, snapshot, and diff so every command runs as written. Update all sample outputs and timestamps to what the CLI prints today, including the new TAGS, POLICIES, and COMPLIANT columns, and use a snapshot pair that actually differs for the diff example.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
The stale "Scaled up" line is removed as part of the full tutorial refresh in #413, so this PR no longer needs to touch the file.
|
Claude encountered an error after 4m 30s —— View job Doc reviewChecked the three tutorials at branch head ( Three findings. Improvement — the sweep stops one page shortLocation: Those two commands are the site's fourth and fifth cyber-dojo invocations, and they still read: kosli list envs --org cyber-dojo --http-proxy http://localhost:8888 --api-token <your-token>Both defects this PR removed from the other three pages are still here: the reader is told they need a token for an org that does not require one, and Recommendation: drop Improvement — "public organization" is now load-bearing in six places and documented in noneLocation: The three tutorials now rest on a product behavior — a public organization is readable without a valid token, and organization visibility overrides the per-flow Recommendation: add one sentence to Suggestion — three sibling pages, three different Setup shapesLocation: That page puts the explanatory sentence above the code block, so it tells the reader to "replace Recommendation: move line 19 below the code block, and add the same sentence after the block on the 2 Improvements, 1 Suggestion, 0 Critical. None of them blocks the merge — the refresh itself is accurate against the current cyber-dojo data. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
- Move the elision marker out of the History list and say that kosli search prints further artifacts as separate blocks. - Narrow the visibility note: the CLI needs a token, so say any valid token can read the public cyber-dojo org rather than "without logging in", and point readers without a token at the published read-only one. - Add the same visibility note to the commit-to-production tutorial, whose list flows output has the same private column.
|
Review findings addressed in ab52faa:
That other tutorial is otherwise as stale as this one was (2022 data, archived flow names). Worth its own refresh, separate from this PR. |
…e webhook event_type (#412) ## Summary The Kosli Actions page described the "Artifact changed" trigger as firing "when instances of an artifact are scaled up or down". Scaling events are no longer recorded, and that trigger fires when an artifact that is already running becomes compliant or non-compliant, or gains new provenance. Readers who set it up expecting a notification on a new deployment got nothing. Changes to `integrations/kosli_actions.md`: - Replace the six-bullet trigger list with a table mapping UI label to API value and stating the exact condition for each trigger. The "Artifact changed" row says explicitly that it does not fire for new deployments. - Add a note that `ON_SCALED_ARTIFACT` keeps its historical name for API compatibility and never fires on replica count changes. - Link the table to the API reference and the Terraform `kosli_action` page so readers can connect the three surfaces. - Correct the webhook example from `ARTIFACT_STARTED` to `STARTED_ARTIFACT` and list all six possible `event_type` values below it. Adjacent stale scaling prose, flagged in review: - `tutorials/following_a_git_commit_to_runtime_environments.md`: the description no longer lists "instance scaling" as a runtime event Kosli shows. - `tutorials/querying_kosli.md`: the stale "Scaled up from 1 to 3" line is handled by the full tutorial refresh in #413 instead, so this PR no longer touches that file. The upstream fix for the Terraform `kosli_action` example and schema descriptions is kosli-dev/terraform-provider-kosli#262. Closes #411 ## Verification - The API link target was checked against the live OpenAPI spec: `PUT /actions/{org}/environments` has the summary "Create or update environment action", which slugifies to the linked path. - `mint broken-links` reports one broken link, in `tutorials/working_with_controls.mdx`. It pre-exists on `main` and is unrelated to this change.
Verified against cyber-dojo: a bogus token reads every flow and artifact, and only an unset token fails, because the CLI refuses to run without one. Say so instead of "any valid token".
The <your-api-token> placeholder is not copy-pasteable and the page now says you can follow it before you have a token. Use the read-only token the CLI reference live examples already publish, in the same shape, and drop the claim that the server does not check the token.
A literal that looks like a real token invites secret scanners and implies one is required. cyber-dojo is public, so any non-empty value works; use KOSLI_API_TOKEN=ignored and say so.
- Make the API token prerequisite optional on the commit-to-production and incident-tracing tutorials, matching the querying tutorial. - Replace the incident-tracing Setup block with the same placeholder token used by the other two, and drop "any authenticated user". - Refresh the commit-to-production list flows table from today's output; it listed two flows that no longer exist. - Mention --show-unchanged for an empty snapshot diff.
2 participants
Summary
Running
tutorials/querying_kosli.mdas written no longer works. cyber-dojo renamed its flows to*-ci, sokosli list artifacts --flow creatorandkosli get artifact creator:344430dfail with "Flow named 'creator' does not exist". The search example resolves to an archived flow with 2022 timestamps, and theaws-beta aws-beta~1diff example prints nothing today because the two latest snapshots run the same artifacts.This refresh:
creator99d7b74) through every step: search, list artifacts, get artifact, the snapshot where it started running, and the diff that shows its deployment.aws-beta#8339vs#8338) for the diff example, explains that an empty diff means nothing changed, and mentions--show-unchanged.VISIBILITYcolumn: a legacy per-flow field that does not control access. Access comes from the organization's visibility. This spawned chore: drop the VISIBILITY column fromkosli list flowscli#1169 to drop the column.Setup sweep across the three cyber-dojo tutorials, from review:
querying_kosli,following_a_git_commit_to_runtime_environments,tracing_a_production_incident_back_to_git_commits) now use the same copy-pasteable Setup block withKOSLI_API_TOKEN=ignored, since cyber-dojo is public and the CLI only needs a non-empty value. A placeholder is used deliberately instead of a real-looking token, to avoid secret scanners and to avoid implying a real token is required.kosli list flowstable is refreshed; it listed two flows that no longer exist. The rest of that page is still stale and deserves its own refresh.No page files move, no navigation or redirect changes.
Verification
Every command on the querying page was run against cyber-dojo on 2026-09-14 and the outputs pasted from those runs, trimmed with
[...]where long. The placeholder token was verified to read every flow.Related: #412 also touched
following_a_git_commit_to_runtime_environments.md(frontmatter description only). The hunks do not overlap.