Skip to content

Commit 3a69eb3

Browse files
dangrondahldangrondahl
committed
feat: add Kosli Learning Labs section
Surfaces the kosli-dev/labs training series inside the docs site as a dedicated Labs tab with five progressive labs (account setup through runtime compliance). Includes repositioning of the existing local demo tutorial and cross-references throughout.
1 parent 4d166a9 commit 3a69eb3

15 files changed

Lines changed: 1241 additions & 290 deletions

‎docs.json‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,10 @@
3939
{
4040
"source": "/ci-defaults",
4141
"destination": "/integrations/ci_cd"
42+
},
43+
{
44+
"source": "/tutorials/get_familiar_with_kosli",
45+
"destination": "/tutorials/try_kosli_locally"
4246
}
4347
],
4448
"navigation": {
@@ -100,7 +104,7 @@
100104
{
101105
"group": "Getting started",
102106
"pages": [
103-
"tutorials/get_familiar_with_Kosli",
107+
"tutorials/try_kosli_locally",
104108
"tutorials/cli_and_http_proxy"
105109
]
106110
},
@@ -154,6 +158,22 @@
154158
}
155159
]
156160
},
161+
{
162+
"tab": "Labs",
163+
"groups": [
164+
{
165+
"group": "Kosli Learning Labs",
166+
"pages": [
167+
"labs/index",
168+
"labs/lab-01-get-ready",
169+
"labs/lab-02-flows-and-trails",
170+
"labs/lab-03-build-controls",
171+
"labs/lab-04-release-controls",
172+
"labs/lab-05-runtime-controls"
173+
]
174+
}
175+
]
176+
},
157177
{
158178
"tab": "Implementation Guide",
159179
"groups": [
@@ -513,7 +533,7 @@
513533
"items": [
514534
{
515535
"label": "Labs",
516-
"href": "https://github.com/kosli-dev/labs"
536+
"href": "/labs"
517537
},
518538
{
519539
"label": "Blog",

‎getting_started/flows.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ A Flow template is a YAML file following the syntax outlined in the [flow templa
2727

2828
Here is an example:
2929

30-
```yml sw-delivery-template.yml
30+
```yaml sw-delivery-template.yml
3131
version: 1
3232
trail:
3333
attestations:

‎getting_started/install.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,10 @@ icon: "download"
116116
</Step>
117117
</Steps>
118118

119+
<Info>
120+
New to Kosli? The [Kosli Learning Labs](/labs) provide a guided, project-based introduction covering Flows, Trails, attestations, and runtime compliance.
121+
</Info>
122+
119123
## Using the CLI
120124

121125
The [CLI Reference](/client_reference/) section contains all the information you may need to run the Kosli CLI. The CLI flags offer flexibility for configuration and can be assigned in three distinct manners:

‎images/labs/first-trail.png‎

165 KB
Loading

‎images/labs/pipeline.png‎

18.5 KB
Loading

‎index.mdx‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,18 @@ Get your documentation site up and running in minutes.
3232
</Columns>
3333
<Columns cols={3}>
3434
<Card
35-
title="Get familiar with Kosli"
36-
icon="book-open"
37-
href="/tutorials/get_familiar_with_kosli/"
35+
title="Try Kosli locally"
36+
icon="laptop"
37+
href="/tutorials/try_kosli_locally"
3838
>
39-
Learn how to use Kosli with simple examples.
39+
A 10-minute Docker-based demo, no GitHub account required.
40+
</Card>
41+
<Card
42+
title="Kosli Learning Labs"
43+
icon="flask"
44+
href="/labs"
45+
>
46+
A hands-on five-lab series from setup to runtime compliance.
4047
</Card>
4148
<Card
4249
title="Command reference"
@@ -45,12 +52,4 @@ Get your documentation site up and running in minutes.
4552
>
4653
All Kosli commands in one place.
4754
</Card>
48-
<Card
49-
title="Join the community"
50-
icon="slack"
51-
href="https://www.kosli.com/community/"
52-
new_page
53-
>
54-
Join the Kosli Slack Community.
55-
</Card>
5655
</Columns>

‎labs/index.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Kosli Learning Labs
3+
description: "A hands-on five-lab series taking you from your first Kosli account to full supply chain compliance enforcement."
4+
icon: flask
5+
---
6+
7+
These labs provide a progressive, practical introduction to Kosli's core features. You'll learn how to track your software delivery process from build through deployment, establish compliance requirements, and maintain complete visibility into your software supply chain.
8+
9+
Each lab builds on the previous one — complete them in order.
10+
11+
<Info>
12+
Want something shorter first? [Try Kosli locally](/tutorials/get_familiar_with_Kosli) is a 10-minute Docker-based demo that requires no GitHub account or CI pipeline.
13+
</Info>
14+
15+
<Info>
16+
**Prerequisites**: A GitHub account, basic familiarity with Git and CI/CD concepts. No prior Kosli experience required.
17+
</Info>
18+
19+
<CardGroup cols={2}>
20+
<Card title="Lab 1: Get Ready" icon="rocket" href="/labs/lab-01-get-ready">
21+
Create a Kosli account, fork the sample repository, and verify the CI/CD pipeline runs successfully.
22+
</Card>
23+
<Card title="Lab 2: Flows and Trails" icon="code-branch" href="/labs/lab-02-flows-and-trails">
24+
Install the Kosli CLI, create Flows and Trails, and integrate them into your GitHub Actions workflow.
25+
</Card>
26+
<Card title="Lab 3: Build Controls" icon="shield-check" href="/labs/lab-03-build-controls">
27+
Attest artifacts, attach JUnit test results, and generate and attest a Software Bill of Materials.
28+
</Card>
29+
<Card title="Lab 4: Release Controls" icon="lock" href="/labs/lab-04-release-controls">
30+
Define compliance requirements with Flow Templates and gate deployments with `kosli assert artifact`.
31+
</Card>
32+
<Card title="Lab 5: Runtime Controls" icon="server" href="/labs/lab-05-runtime-controls">
33+
Create environments, snapshot what's running in production, and enforce compliance policies.
34+
</Card>
35+
</CardGroup>
36+
37+
<Note>
38+
The labs use a sample Java application with a pre-built GitHub Actions pipeline. You'll progressively add Kosli integration to that pipeline across Labs 2–5.
39+
</Note>
40+
41+
The standalone lab repository is also available at [github.com/kosli-dev/labs](https://github.com/kosli-dev/labs).

‎labs/lab-01-get-ready.mdx‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: "Lab 1: Get Ready"
3+
description: "Create a Kosli account, fork the sample repository, verify the CI/CD pipeline, and install the Kosli CLI."
4+
icon: rocket
5+
---
6+
7+
## Learning goals
8+
9+
- Create a Kosli account and organization
10+
- Create a copy of the sample application repository
11+
- Verify the CI/CD pipeline runs successfully
12+
- Install the Kosli CLI and create an API key
13+
- Understand the basic structure of the application and its deployment process
14+
15+
## Introduction
16+
17+
Before diving into Kosli's features, you need to set up your account and verify that your sample application builds and deploys correctly.
18+
19+
This lab uses a simple Java application with a complete CI/CD pipeline already configured in GitHub Actions. The pipeline builds the application, creates a Docker image, runs tests, and deploys it. In subsequent labs, you'll integrate Kosli to track all these activities.
20+
21+
## Exercise
22+
23+
<Steps>
24+
<Step title="Create a Kosli account">
25+
- Navigate to [app.kosli.com/sign-up](https://app.kosli.com/sign-up)
26+
- Choose to sign up with GitHub
27+
- Complete the registration process and verify your email if required
28+
- Log in to [app.kosli.com](https://app.kosli.com)
29+
</Step>
30+
31+
<Step title="Fork the sample repository">
32+
- Navigate to [github.com/kosli-dev/labs](https://github.com/kosli-dev/labs)
33+
- Click the **Use this template** button in the top-right corner
34+
- Select **Create a new repository**
35+
- Set your personal GitHub account as the **Owner** and name the repository `labs`
36+
- Click **Create repository from template**
37+
38+
<Tip>
39+
From now on, "your repository" refers to your copy of the labs repository at `https://github.com/YOUR-GITHUB-USERNAME/labs`.
40+
</Tip>
41+
</Step>
42+
43+
<Step title="Enable GitHub Actions">
44+
1. Go to your repository on GitHub
45+
2. Click the **Actions** tab
46+
3. If prompted, click **I understand my workflows, go ahead and enable them**
47+
4. If the workflow doesn't start automatically, trigger it manually:
48+
- Click **Main workflow** in the left sidebar
49+
- Click **Run workflow**, select `main`, and click **Run workflow**
50+
</Step>
51+
52+
<Step title="Verify the pipeline">
53+
In the **Actions** tab, click the most recent workflow run and observe the jobs:
54+
55+
| Job | What it does |
56+
|-----|-------------|
57+
| Build | Compiles the Java application using Gradle |
58+
| Linting | Checks code quality (warnings are expected) |
59+
| Docker-image | Builds and pushes a Docker container image |
60+
| Security-scan | Scans the Docker image for vulnerabilities |
61+
| Component-test | Runs integration tests |
62+
| Performance-test | Runs basic performance checks |
63+
| Deploy | Starts and stops the application container |
64+
65+
Wait for all jobs to show green checkmarks.
66+
67+
<Frame>
68+
<img src="/images/labs/pipeline.png" alt="GitHub Actions pipeline showing all jobs completing successfully" />
69+
</Frame>
70+
71+
<Tip>
72+
The pipeline may take 3–6 minutes on the first run. GitHub Actions provides free minutes for public repositories.
73+
</Tip>
74+
75+
<Accordion title="Common issues">
76+
- **Docker-image job fails with permission error**: Make sure your repository has package write permissions enabled.
77+
- **Linting shows warnings**: This is expected and won't fail the build (`DISABLE_ERRORS` is set to `true`).
78+
</Accordion>
79+
</Step>
80+
81+
<Step title="Install the Kosli CLI">
82+
Run the one-line install script:
83+
84+
```bash
85+
curl -fL https://raw.githubusercontent.com/kosli-dev/cli/refs/heads/main/install-cli.sh | sh
86+
87+
# Verify installation
88+
kosli version
89+
```
90+
91+
<Tip>
92+
If this method fails, see [Install Kosli CLI](/getting_started/install) for alternative installation options (Homebrew, APT, Docker, etc.).
93+
</Tip>
94+
</Step>
95+
96+
<Step title="Create a Kosli API key">
97+
- Log in to [app.kosli.com/settings/profile](https://app.kosli.com/settings/profile)
98+
- Navigate to the **API Keys** section
99+
- Click **Add API Key**, give it a name (e.g., "CLI Access"), and copy the key immediately — it won't be shown again
100+
101+
Configure it for local use:
102+
103+
```bash
104+
export KOSLI_API_TOKEN="your-api-key-here"
105+
export KOSLI_ORG="your-gh-username"
106+
```
107+
108+
Verify the CLI can reach Kosli:
109+
110+
```bash
111+
kosli list flows
112+
```
113+
114+
You should see "No flows were found" — which confirms authentication is working.
115+
116+
<Warning>
117+
Never commit API keys to your repository. You'll add this key to GitHub Secrets in Lab 2.
118+
</Warning>
119+
120+
See [Service Accounts](/getting_started/service-accounts) for more on API key management.
121+
</Step>
122+
123+
<Step title="Explore the workflow file">
124+
In your repository, navigate to `.github/workflows/full-pipeline.yaml` and review the structure:
125+
126+
- Notice how it triggers on every push
127+
- Observe the environment variables at the top
128+
- See how artifacts are shared between jobs using `upload-artifact` and `download-artifact`
129+
- Note the dependencies between jobs (e.g., Docker-image requires Build to complete first)
130+
131+
In later labs, you'll add Kosli integration to this file.
132+
</Step>
133+
134+
<Step title="View the published Docker image">
135+
1. Go to your GitHub profile page
136+
2. Click the **Packages** tab
137+
3. You should see the `labs` package
138+
4. Click it to view the Docker image details — note the image tag (`latest`) and SHA digest
139+
140+
<Tip>
141+
The Docker image is automatically published to GitHub Container Registry (`ghcr.io`) by the pipeline.
142+
</Tip>
143+
</Step>
144+
</Steps>
145+
146+
## Verification checklist
147+
148+
Before moving to the next lab, confirm:
149+
150+
- [ ] Kosli account created at app.kosli.com
151+
- [ ] Copy of the labs repository under your GitHub account
152+
- [ ] GitHub Actions completed all jobs successfully
153+
- [ ] Docker image published to your GitHub Container Registry
154+
- [ ] Kosli CLI installed (`kosli version` works)
155+
- [ ] API key created and `kosli list flows` returns successfully
156+
- [ ] You understand the basic pipeline structure
157+
158+
## Next steps
159+
160+
Continue to [Lab 2: Flows and Trails](/labs/lab-02-flows-and-trails) to create your first Flow and Trail and integrate them into your pipeline.

0 commit comments

Comments
 (0)