Skip to content

feat: embed live-docs at deployment #207

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JonJagger merged 14 commits into from
May 5, 2026
Merged

feat: embed live-docs at deployment #207

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
57ba366
feat: generate live-docs sections statically at deployment time
JonJagger May 5, 2026
06b169e
feat: implement real yaml and event URL resolution
JonJagger May 5, 2026
600c5ce
refactor: replace live_docs_cache with live_docs_fetch
JonJagger May 5, 2026
2e9d5c6
refactor: consolidate all resolution logic into live_docs_fetch.py
JonJagger May 5, 2026
79ddfc0
feat: add kosli evaluate input to _MODIFIERS
JonJagger May 5, 2026
5889d79
feat: bring audit_live_docs_backup_commits.py into docs repo
JonJagger May 5, 2026
6de555a
feat: bring refresh_live_docs_backup_commits.py into docs repo
JonJagger May 5, 2026
97a156b
feat: embed static CLI query examples at deployment time
JonJagger May 5, 2026
0706803
fix: move read-only API token comment above the export line
JonJagger May 5, 2026
53d6643
rename: resolve_livedocs.py -> add_livedocs.py
JonJagger May 5, 2026
0a95fe9
feat: add live-docs unit tests ported from server
JonJagger May 5, 2026
dbb792d
rename: live-docs.sh -> scripts/dev_live_docs.sh
JonJagger May 5, 2026
db5b7e9
ci: run live-docs tests in update-cli-docs workflow
JonJagger May 5, 2026
46c35fc
ci: move live-docs tests to pr-quality workflow
JonJagger May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .github/workflows/pr-quality.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,27 @@ on:
- synchronize

jobs:
test-live-docs:
name: Test live-docs scripts
runs-on: ubuntu-latest
steps:
- name: Harden Runner
uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
with:
egress-policy: audit

- uses: actions/checkout@v6

- uses: actions/setup-python@v6
with:
python-version: '3.14'

- name: Install dependencies
run: pip install requests pytest

- name: Run tests
run: pytest tests/

validate-title:
name: Validate PR Title
runs-on: ubuntu-latest
Expand Down
5 changes: 4 additions & 1 deletion .github/workflows/update-cli-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ jobs:
python-version: '3.14'

- name: Install Python dependencies
run: pip install pyyaml
run: pip install pyyaml requests

- name: Stamp CLI version in overview page
run: |
Expand All @@ -62,6 +62,9 @@ jobs:
- name: Update CLI navigation
run: python scripts/update-cli-nav.py --docs-dir client_reference/ --nav-file config/navigation.json

- name: Add live-docs sections
run: python scripts/add_livedocs.py
Comment thread
JonJagger marked this conversation as resolved.

- name: Install helm-docs
run: |
curl -sL https://github.com/norwoodj/helm-docs/releases/download/v1.14.2/helm-docs_1.14.2_Linux_x86_64.deb --output helm-docs.deb
Expand Down
4 changes: 2 additions & 2 deletions client_reference/kosli_assert_artifact.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,12 +69,12 @@ non-zero code if non-compliant status.
<Tab title="GitHub">
View an example of the `kosli assert artifact` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Bassert%2Bartifact)
In [this YAML file](https://github.com/cyber-dojo/differ/blob/30dffd09c3f896a322c65029247abcea3019c43a/.github/workflows/main.yml#L329)
</Tab>
<Tab title="GitLab">
View an example of the `kosli assert artifact` command in GitLab.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Bassert%2Bartifact)
In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/b3152a10de1f36b7dbe2818c0918af06fd3aca61/.gitlab/workflows/main.yml#L153)
</Tab>
</Tabs>

Expand Down
4 changes: 2 additions & 2 deletions client_reference/kosli_attest_artifact.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,12 +80,12 @@ In other CI systems, set them explicitly to capture repository metadata.
<Tab title="GitHub">
View an example of the `kosli attest artifact` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Battest%2Bartifact), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Battest%2Bartifact).
In [this YAML file](https://github.com/cyber-dojo/reusable-actions-workflows/blob/25f0b797c18403de1c8490a9a71bbe9789c809a9/.github/workflows/secure-docker-build.yml#L210), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/differ-ci/trails/30dffd09c3f896a322c65029247abcea3019c43a?attestation_id=046919b1-42dd-47f8-8569-912d0259).
</Tab>
<Tab title="GitLab">
View an example of the `kosli attest artifact` command in GitLab.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Battest%2Bartifact), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=gitlab&command=kosli%2Battest%2Bartifact).
In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c/.gitlab/workflows/main.yml#L111), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/creator-ci/trails/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c?attestation_id=c5d209a3-9139-4f5b-a553-c6351091).
</Tab>
</Tabs>

Expand Down
2 changes: 1 addition & 1 deletion client_reference/kosli_attest_custom.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ In other CI systems, set them explicitly to capture repository metadata.
<Tab title="GitHub">
View an example of the `kosli attest custom` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Battest%2Bcustom), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Battest%2Bcustom).
In [this YAML file](https://github.com/cyber-dojo/differ/blob/30dffd09c3f896a322c65029247abcea3019c43a/.github/workflows/main.yml#L203), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/differ-ci/trails/30dffd09c3f896a322c65029247abcea3019c43a?attestation_id=8a32a0bb-c995-41d1-8f2f-c78619b3).
</Tab>
</Tabs>

Expand Down
4 changes: 2 additions & 2 deletions client_reference/kosli_attest_generic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,12 @@ In other CI systems, set them explicitly to capture repository metadata.
<Tab title="GitHub">
View an example of the `kosli attest generic` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Battest%2Bgeneric), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Battest%2Bgeneric).
In [this YAML file](https://github.com/cyber-dojo/dashboard/blob/a6ece2b597888f7ab149759daadda08e3afab0c1/.github/workflows/main.yml#L249), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/dashboard-ci/trails/a6ece2b597888f7ab149759daadda08e3afab0c1?attestation_id=4223c865-5232-461e-b065-ea46aa5d).
</Tab>
<Tab title="GitLab">
View an example of the `kosli attest generic` command in GitLab.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Battest%2Bgeneric), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=gitlab&command=kosli%2Battest%2Bgeneric).
In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c/.gitlab/workflows/main.yml#L92), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/creator-ci/trails/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c?attestation_id=27c3762e-631f-429d-863a-99a3d404).
</Tab>
</Tabs>

Expand Down
4 changes: 2 additions & 2 deletions client_reference/kosli_attest_junit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,12 +79,12 @@ In other CI systems, set them explicitly to capture repository metadata.
<Tab title="GitHub">
View an example of the `kosli attest junit` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Battest%2Bjunit), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Battest%2Bjunit).
In [this YAML file](https://github.com/cyber-dojo/differ/blob/30dffd09c3f896a322c65029247abcea3019c43a/.github/workflows/main.yml#L126), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/differ-ci/trails/30dffd09c3f896a322c65029247abcea3019c43a?attestation_id=ac559624-fe12-4d8e-9f20-334c8d0d).
</Tab>
<Tab title="GitLab">
View an example of the `kosli attest junit` command in GitLab.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Battest%2Bjunit), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=gitlab&command=kosli%2Battest%2Bjunit).
In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c/.gitlab/workflows/main.yml#L126), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/creator-ci/trails/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c?attestation_id=7c731680-ff9f-4e22-8147-32e8629f).
</Tab>
</Tabs>

Expand Down
2 changes: 1 addition & 1 deletion client_reference/kosli_attest_pullrequest_github.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ The attestation can be bound to an *artifact* in two ways:
<Tab title="GitHub">
View an example of the `kosli attest pullrequest github` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Battest%2Bpullrequest%2Bgithub), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Battest%2Bpullrequest%2Bgithub).
In [this YAML file](https://github.com/cyber-dojo/differ/blob/30dffd09c3f896a322c65029247abcea3019c43a/.github/workflows/main.yml#L95), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/differ-ci/trails/30dffd09c3f896a322c65029247abcea3019c43a?attestation_id=a3c84fec-c679-4536-83df-35d25f2d).
</Tab>
</Tabs>

Expand Down
2 changes: 1 addition & 1 deletion client_reference/kosli_attest_pullrequest_gitlab.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ The attestation can be bound to an *artifact* in two ways:
<Tab title="GitLab">
View an example of the `kosli attest pullrequest gitlab` command in GitLab.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Battest%2Bpullrequest%2Bgitlab), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=gitlab&command=kosli%2Battest%2Bpullrequest%2Bgitlab).
In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c/.gitlab/workflows/main.yml#L75), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/creator-ci/trails/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c?attestation_id=763af9cc-b908-456d-935c-f4deb860).
</Tab>
</Tabs>

Expand Down
4 changes: 2 additions & 2 deletions client_reference/kosli_attest_snyk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,12 +83,12 @@ In other CI systems, set them explicitly to capture repository metadata.
<Tab title="GitHub">
View an example of the `kosli attest snyk` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Battest%2Bsnyk), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Battest%2Bsnyk).
In [this YAML file](https://github.com/cyber-dojo/snyk-container-test/blob/43373102aa2abee72027e2aba050adea9fdb0173/action.yml#L70), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/differ-ci/trails/2e482ef95263c81570a82f0456b026e29203d550?attestation_id=c4d17fb4-05d2-4894-bca7-f21e56ab).
</Tab>
<Tab title="GitLab">
View an example of the `kosli attest snyk` command in GitLab.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Battest%2Bsnyk), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=gitlab&command=kosli%2Battest%2Bsnyk).
In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/a184b5b7d2053ce2b2f7064bf46f0b6f72f9f393/.gitlab/workflows/main.yml#L146), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/creator-ci/trails/a184b5b7d2053ce2b2f7064bf46f0b6f72f9f393?attestation_id=3e9cd5ee-4fd3-403f-ba59-6d431dec).
</Tab>
</Tabs>

Expand Down
2 changes: 1 addition & 1 deletion client_reference/kosli_attest_sonar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ The attestation can be bound to an *artifact* in two ways:
<Tab title="GitHub">
View an example of the `kosli attest sonar` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Battest%2Bsonar), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Battest%2Bsonar).
In [this YAML file](https://github.com/cyber-dojo/dashboard/blob/a6ece2b597888f7ab149759daadda08e3afab0c1/.github/workflows/main.yml#L166), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/dashboard-ci/trails/a6ece2b597888f7ab149759daadda08e3afab0c1?attestation_id=2377ce1f-f4b4-47c4-8458-8f16de62).
</Tab>
</Tabs>

Expand Down
4 changes: 2 additions & 2 deletions client_reference/kosli_begin_trail.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,12 +61,12 @@ In other CI systems, set them explicitly to capture repository metadata.
<Tab title="GitHub">
View an example of the `kosli begin trail` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Bbegin%2Btrail), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Bbegin%2Btrail).
In [this YAML file](https://github.com/cyber-dojo/runner/blob/a2ffba5a5debbc8f4f199cf5a88e5899c7d6547e/.github/workflows/main.yml#L78), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/runner-ci/trails/a2ffba5a5debbc8f4f199cf5a88e5899c7d6547e?attestation_id=1).
</Tab>
<Tab title="GitLab">
View an example of the `kosli begin trail` command in GitLab.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Bbegin%2Btrail), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=gitlab&command=kosli%2Bbegin%2Btrail).
In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c/.gitlab/workflows/main.yml#L55), which created [this Kosli Event](https://app.kosli.com/cyber-dojo/flows/creator-ci/trails/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c?attestation_id=1).
</Tab>
</Tabs>

Expand Down
2 changes: 1 addition & 1 deletion client_reference/kosli_create_attestation-type.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ All rules must return `true` for the evaluation to pass and the attestation to b
<Tab title="GitHub">
View an example of the `kosli create attestation-type` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Bcreate%2Battestation-type)
In [this YAML file](https://github.com/cyber-dojo/kosli-attestation-types/blob/7ad343982d42654fdf4cf123c5e7aec44af8e1a7/.github/workflows/main.yml#L56)
</Tab>
</Tabs>

Expand Down
4 changes: 2 additions & 2 deletions client_reference/kosli_create_flow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,12 @@ You can specify flow parameters in flags.
<Tab title="GitHub">
View an example of the `kosli create flow` command in GitHub.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Bcreate%2Bflow), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Bcreate%2Bflow).
In [this YAML file](https://github.com/cyber-dojo/runner/blob/a2ffba5a5debbc8f4f199cf5a88e5899c7d6547e/.github/workflows/main.yml#L71)
</Tab>
<Tab title="GitLab">
View an example of the `kosli create flow` command in GitLab.

In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Bcreate%2Bflow), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=gitlab&command=kosli%2Bcreate%2Bflow).
In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/65fd2bfa2478534ea4bc5ccf30f6bfc6aab7550c/.gitlab/workflows/main.yml#L53)
</Tab>
</Tabs>

Expand Down
Loading