From 88d3ca5b41a4aa20a97234255fa4f4217967edfb Mon Sep 17 00:00:00 2001 From: Patrice Boisclair-Laberge Date: Fri, 18 Sep 2026 14:18:05 +0000 Subject: [PATCH] docs(kiln): add the Kiln product tab Add a Kiln tab with the customer documentation for Trunk's CI product. The pages come from apps/firewatch/docs/kiln in trunk-io/trunk-cloud, generated by the docs sync tool. The pages carry the firewatch access group, the same as the Trunk Workspaces pages. This adds only the Kiln tab and pages. It does not change the Workspaces pages. --- docs.json | 42 ++++++++++++++++ kiln/.sync.json | 5 ++ kiln/actions/run-as.mdx | 45 ++++++++++++++++++ kiln/actions/runs-on.mdx | 65 +++++++++++++++++++++++++ kiln/actions/sizes.mdx | 46 ++++++++++++++++++ kiln/actions/templates-and-regions.mdx | 40 ++++++++++++++++ kiln/cache/index.mdx | 46 ++++++++++++++++++ kiln/cache/settings.mdx | 36 ++++++++++++++ kiln/getting-started.mdx | 66 ++++++++++++++++++++++++++ kiln/index.mdx | 56 ++++++++++++++++++++++ kiln/reference/runs-on-grammar.mdx | 53 +++++++++++++++++++++ kiln/roadmap.mdx | 45 ++++++++++++++++++ kiln/settings/ci-defaults.mdx | 34 +++++++++++++ kiln/settings/limits-and-priority.mdx | 34 +++++++++++++ 14 files changed, 613 insertions(+) create mode 100644 kiln/.sync.json create mode 100644 kiln/actions/run-as.mdx create mode 100644 kiln/actions/runs-on.mdx create mode 100644 kiln/actions/sizes.mdx create mode 100644 kiln/actions/templates-and-regions.mdx create mode 100644 kiln/cache/index.mdx create mode 100644 kiln/cache/settings.mdx create mode 100644 kiln/getting-started.mdx create mode 100644 kiln/index.mdx create mode 100644 kiln/reference/runs-on-grammar.mdx create mode 100644 kiln/roadmap.mdx create mode 100644 kiln/settings/ci-defaults.mdx create mode 100644 kiln/settings/limits-and-priority.mdx diff --git a/docs.json b/docs.json index 8843e9c4..bec19a58 100644 --- a/docs.json +++ b/docs.json @@ -730,6 +730,48 @@ } ] }, + { + "tab": "Kiln", + "groups": [ + { + "group": "Overview", + "pages": [ + "kiln/index", + "kiln/getting-started" + ] + }, + { + "group": "GitHub Actions", + "pages": [ + "kiln/actions/runs-on", + "kiln/actions/sizes", + "kiln/actions/templates-and-regions", + "kiln/actions/run-as" + ] + }, + { + "group": "Caching", + "pages": [ + "kiln/cache/index", + "kiln/cache/settings" + ] + }, + { + "group": "Organization settings", + "pages": [ + "kiln/settings/ci-defaults", + "kiln/settings/limits-and-priority" + ] + }, + { + "group": "Reference", + "pages": [ + "kiln/reference/runs-on-grammar", + "kiln/roadmap" + ] + } + ] + }, { "tab": "Changelog", "hidden": true, diff --git a/kiln/.sync.json b/kiln/.sync.json new file mode 100644 index 00000000..b8f2c697 --- /dev/null +++ b/kiln/.sync.json @@ -0,0 +1,5 @@ +{ + "generatedFrom": "trunk-io/trunk-cloud", + "sourceRef": "firewatch-kiln-docs", + "sourceSha": "948fdb07d44d9eb99f4ff791ddae442c11c65372" +} diff --git a/kiln/actions/run-as.mdx b/kiln/actions/run-as.mdx new file mode 100644 index 00000000..e105e91e --- /dev/null +++ b/kiln/actions/run-as.mdx @@ -0,0 +1,45 @@ +--- +title: "Run as a user" +description: "Run a job as the person who started it, not a shared CI identity." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + + + This feature is in Beta. It may be off for your organization. Ask the Trunk + team to turn it on. + + +By default, a Kiln job runs as a shared CI identity. With `run-as`, a job runs as +the real person who started it. This makes the job's actions and logs belong to +that person. + +Trunk finds the person from the GitHub event that started the job. You do not name +a user in the label. The label only says that the job should run as its actor. + +## Modes + +Add `run-as` with one of two modes: + +| Mode | When it applies | +| ------------------- | -------------------------------------------------------------------- | +| `run-as=dispatcher` | A run you start by hand (`workflow_dispatch`) on the default branch. | +| `run-as=actor` | A `push` or a pull request on any branch. | + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..run-as=dispatcher +``` + +## Rules + +- **The job never fails because of `run-as`.** If Trunk cannot find the person, + the job runs as the shared CI identity instead. +- **A pull request from a fork does not run as a user.** Trunk refuses it for + safety. +- **The person must be a member of your organization.** + + + Use `run-as` when a job acts on a person's behalf, such as a coding agent that + works in the job. The job then uses that person's identity. + diff --git a/kiln/actions/runs-on.mdx b/kiln/actions/runs-on.mdx new file mode 100644 index 00000000..3d18b4d3 --- /dev/null +++ b/kiln/actions/runs-on.mdx @@ -0,0 +1,65 @@ +--- +title: "The runs-on label" +description: "One label selects the Kiln runner and sets its options." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +You point a job at Kiln with one `runs-on` label. The label starts with the Kiln +anchor and adds options after it. Each option uses `key=value`, and `..` joins the +options. + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium +``` + + + The anchor holds a unique value per run: `${{ github.run_id }}-${{ + github.run_attempt }}`. This value keeps each job on its own runner, so one job + never takes another job's runner. + + +## Options + +| Option | Required | What it sets | +| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------- | +| `size` | Yes | The machine size, which sets the CPU count. See [Machine sizes](/kiln/actions/sizes). | +| `memory` | No | `high` for 4 GiB per CPU instead of 2. See [Machine sizes](/kiln/actions/sizes). | +| `template` | No | The template (a prepared environment) for the job. See [Templates and regions](/kiln/actions/templates-and-regions). | +| `region` | No | The region for the job. See [Templates and regions](/kiln/actions/templates-and-regions). | +| `cache` | No | `kiln` or `github` to choose the cache. See [Caching](/kiln/cache/index). | +| `run-as` | No | Run the job as the person who started it. See [Run as a user](/kiln/actions/run-as). | + +Only `size` is required. If you leave out `template` or `region`, the job uses +your [organization defaults](/kiln/settings/ci-defaults). + +## Examples + +A medium runner with high memory: + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=large..memory=high +``` + +A job on a chosen template and region: + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..template=..region=us-west +``` + +## Rules + +- **A wrong key fails the job with a clear message.** A typo never runs the wrong + machine. +- **The order of the options does not matter.** +- **Keys are not case-sensitive.** +- **A key must not repeat.** + + + If a job does not start, read the job's error message first. Kiln reports the + exact reason, such as an unknown option or a missing `size`. + + +See the [full label format](/kiln/reference/runs-on-grammar) for every option in +one table. diff --git a/kiln/actions/sizes.mdx b/kiln/actions/sizes.mdx new file mode 100644 index 00000000..cf28d44f --- /dev/null +++ b/kiln/actions/sizes.mdx @@ -0,0 +1,46 @@ +--- +title: "Machine sizes" +description: "Pick a size to set the CPU count. Ask for high memory when a job needs it." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +The `size` option sets the CPU count of the runner. `size` is required in the +`runs-on` label. + +## Sizes + +| Size | CPUs | +| -------- | ---- | +| `xsmall` | 1 | +| `small` | 2 | +| `medium` | 4 | +| `large` | 8 | +| `xlarge` | 16 | + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=large +``` + + + There is no default size. You must set `size` on every Kiln job. A missing or + unknown size fails the job with a clear message. + + +## Memory + +By default, a runner has 2 GiB of memory per CPU. When a job needs more, add +`memory=high` for 4 GiB per CPU. The size still sets the CPU count. + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=large..memory=high +``` + +A `large` runner with `memory=high` has 8 CPUs and 32 GiB of memory. + + + Start with a size that matches your job. Add `memory=high` only for a job that + runs out of memory, such as a large build or a test suite that holds a lot of + data. + diff --git a/kiln/actions/templates-and-regions.mdx b/kiln/actions/templates-and-regions.mdx new file mode 100644 index 00000000..084a12f0 --- /dev/null +++ b/kiln/actions/templates-and-regions.mdx @@ -0,0 +1,40 @@ +--- +title: "Templates and regions" +description: "Run a job on a chosen template or region, or use your organization defaults." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +A job can run on a chosen template or in a chosen region. If you do not choose, +the job uses your [organization defaults](/kiln/settings/ci-defaults). + +## Templates + +A template is a prepared environment for a job. It holds the tools and the setup +your jobs need, so a job starts ready. Your organization admin creates templates +and sets an organization default. + +Add `template` to run a job on a chosen template: + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..template= +``` + +If you leave out `template`, the job uses the organization default template. + +## Regions + +A region is the location where the job runs. Your organization admin sets a +default region. Add `region` to run a job in a chosen region: + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..region=us-west +``` + +If you leave out `region`, the job uses the organization default region. + + + Ask your organization admin for the template IDs and the regions your + organization can use. + diff --git a/kiln/cache/index.mdx b/kiln/cache/index.mdx new file mode 100644 index 00000000..e2e51603 --- /dev/null +++ b/kiln/cache/index.mdx @@ -0,0 +1,46 @@ +--- +title: "Caching" +description: "The shared cache lets jobs reuse build results, so they finish faster." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +Kiln has a shared build cache. Jobs reuse build results across runs, so they +finish faster. The cache is on by default. + +## What the cache supports + +The shared cache works with the GitHub Actions cache and common build tools: + +- The GitHub Actions cache (`actions/cache`) +- `sccache` +- `bazel` +- `gradle` +- `ccache` + +Common build-tool lanes work with no setup. To choose the cache for the GitHub +Actions cache on one job, use the `cache` option. + +## The cache option + +Add `cache` to the `runs-on` label to choose the cache for a job: + +| Value | Effect | +| -------------- | ------------------------------------------------------- | +| `cache=kiln` | Use the Kiln shared cache for the GitHub Actions cache. | +| `cache=github` | Use the GitHub cache for that job. | + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium..cache=kiln +``` + + + A fork pull request gets read-only cache access. A push to your own repository + can write to the cache. + + +## Turn the cache on or off + +An admin can turn the shared cache off, per repository or for the whole +organization. See [Cache settings](/kiln/cache/settings). diff --git a/kiln/cache/settings.mdx b/kiln/cache/settings.mdx new file mode 100644 index 00000000..ca9e98df --- /dev/null +++ b/kiln/cache/settings.mdx @@ -0,0 +1,36 @@ +--- +title: "Cache settings" +description: "Turn the shared cache on or off, per repository or for the organization." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +The shared cache is on by default. An admin can turn it off. This page shows the +settings and who can change them. + +## Where the setting applies + +| Level | What it controls | +| ------------ | --------------------------------- | +| Repository | The cache for one repository. | +| Organization | The default for every repository. | + +The repository setting wins over the organization default. If a repository has no +setting, the job uses the organization default. If the organization has no +default, the cache is on. + +## Who can change it + +An **organization admin** or a **repository admin** on GitHub can change the +setting. + +## Turn the cache off for one job + +To keep the cache on but skip it for one job, add `cache=github` to the job's +`runs-on` label. See [Caching](/kiln/cache/index). + + + When you turn the cache off, jobs stop reading and writing the shared cache. A + job that already started keeps its cache until it ends. + diff --git a/kiln/getting-started.mdx b/kiln/getting-started.mdx new file mode 100644 index 00000000..67285374 --- /dev/null +++ b/kiln/getting-started.mdx @@ -0,0 +1,66 @@ +--- +title: "Get started" +description: "Turn on Kiln, set your defaults, and run your first job." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +This page shows how to run your first job on Kiln. + + + + Install the Trunk GitHub App on your organization. On a demo call, the Trunk + team turns on Kiln for you and sets up your access. + + + Set an organization default template, region, and size. Most jobs then need + only a size in the label. See + [Organization defaults](/kiln/settings/ci-defaults). + + + Change the `runs-on` label of a job to the Kiln label. The label sets the + machine size. See [The runs-on label](/kiln/actions/runs-on). + + ```yaml + jobs: + build: + runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium + steps: + - uses: actions/checkout@v4 + - run: make build + ``` + + + + Push a commit or start the workflow. Trunk provisions a fresh VM, runs the + job, and removes the VM when the job ends. + + + + + Do you have many workflows to move? Trunk can open a pull request that + rewrites your `runs-on` labels for you. Ask the Trunk team. See the + [Roadmap](/kiln/roadmap). + + +## Next steps + + + + Every option you can set on a job. + + + The sizes, their CPU counts, and high memory. + + + Reuse build results to make jobs faster. + + + Set a CPU limit and mark priority branches. + + diff --git a/kiln/index.mdx b/kiln/index.mdx new file mode 100644 index 00000000..035577f4 --- /dev/null +++ b/kiln/index.mdx @@ -0,0 +1,56 @@ +--- +title: "Kiln" +description: "Run your CI jobs on Trunk-hosted runners. Each job gets a fresh, isolated VM." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +Kiln runs your CI jobs on Trunk-hosted runners. You add one label to a job, and +Trunk runs that job on a fresh, isolated VM. Each job gets a clean machine with +your tools ready. + +## Why Kiln + + + + Every job runs in its own fresh VM. No leftover state from an earlier job. + + + One label sets the CPU count. Ask for more memory when a job needs it. + + + A shared cache lets jobs reuse build results across runs. + + + Set an organization default template, region, and size, so most jobs need + only a size. + + + +## How it works + +You keep your workflows on GitHub. You change one thing: the `runs-on` label of a +job. That label tells Trunk to run the job. Trunk starts a VM, runs the job, and +removes the VM when the job ends. + + + Turn on Kiln for your organization and run your first job. + + +## What you can configure + +- **The runner** — the `runs-on` label sets the size and, when you want, the + region, the template, the cache, and the run identity. See + [The runs-on label](/kiln/actions/runs-on). +- **Caching** — turn the shared cache on or off, per repository or for the whole + organization. See [Caching](/kiln/cache/index). +- **Organization defaults** — set a default template, region, and size. See + [Organization defaults](/kiln/settings/ci-defaults). +- **Limits and priority** — set a CPU limit for CI and mark priority branches. + See [Limits and priority](/kiln/settings/limits-and-priority). + + + Kiln also runs Buildkite jobs, and more features are on the way. See the + [Roadmap](/kiln/roadmap). + diff --git a/kiln/reference/runs-on-grammar.mdx b/kiln/reference/runs-on-grammar.mdx new file mode 100644 index 00000000..8b8b0de8 --- /dev/null +++ b/kiln/reference/runs-on-grammar.mdx @@ -0,0 +1,53 @@ +--- +title: "runs-on label reference" +description: "The full Kiln runs-on label format in one table, with examples." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +This page lists every option of the Kiln `runs-on` label in one place. For a guide +with more context, see [The runs-on label](/kiln/actions/runs-on). + +## Format + +```text +trunk-kiln=..size=[..memory=][..template=][..region=][..cache=][..run-as=] +``` + +- `trunk-kiln=` — the anchor. Use `${{ github.run_id }}-${{ +github.run_attempt }}` for ``, so each job keeps its own runner. +- `..` joins the options. +- Each option is `key=value`. + +## Options + +| Option | Required | Values | Default | +| ---------- | -------- | ---------------------------------------------- | --------------------- | +| `size` | Yes | `xsmall`, `small`, `medium`, `large`, `xlarge` | None | +| `memory` | No | `standard`, `high` | `standard` | +| `template` | No | A template ID | Organization default | +| `region` | No | A region name | Organization default | +| `cache` | No | `kiln`, `github` | On, per your settings | +| `run-as` | No | `dispatcher`, `actor` | Off | + +## Rules + +- The order of the options does not matter. +- Keys are not case-sensitive. +- A key must not repeat. +- A wrong or unknown key fails the job with a clear message. + +## Examples + +A medium runner: + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=medium +``` + +A large runner with high memory, a chosen template, and the Kiln cache: + +```yaml +runs-on: trunk-kiln=${{ github.run_id }}-${{ github.run_attempt }}..size=large..memory=high..template=..cache=kiln +``` diff --git a/kiln/roadmap.mdx b/kiln/roadmap.mdx new file mode 100644 index 00000000..8a742321 --- /dev/null +++ b/kiln/roadmap.mdx @@ -0,0 +1,45 @@ +--- +title: "Roadmap" +description: "Kiln features that are on the way." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +These Kiln features are on the way. Ask the Trunk team about early access. + + + This page lists near-term work. The list can change. A feature here is not yet + ready for every organization. + + +## Coming soon + + + + Run your Buildkite jobs on the same Trunk runners. You target a Kiln queue + and set the size, template, and region with agent tags. + + + Serve public repositories on a hardened runner, so you can run CI on open + repositories with the right guardrails. + + + See and clear your cache entries. View the size, the age, and the usage of + your cache. + + + Trunk opens a pull request that moves your existing jobs onto Kiln, so you + do not edit each workflow by hand. + + + Start a coding agent from a comment on GitHub or Slack. The agent works in a + Trunk workspace. + + + +## In Beta + + + Run a job as the person who started it. Available now in Beta. + diff --git a/kiln/settings/ci-defaults.mdx b/kiln/settings/ci-defaults.mdx new file mode 100644 index 00000000..aa2859f3 --- /dev/null +++ b/kiln/settings/ci-defaults.mdx @@ -0,0 +1,34 @@ +--- +title: "Organization defaults" +description: "Set a default template, region, and size for your CI jobs." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +An organization admin sets the defaults for CI jobs. A job then needs only a size +in its label, and the defaults fill in the rest. + +## The defaults + +| Default | What it sets | +| -------- | --------------------------------------------------------------- | +| Template | The template a job uses when its label has no `template`. | +| Region | The region a job uses when its label has no `region`. | +| Size | The size a job uses in tools that read an organization default. | + +## How a job resolves a value + +For a template or a region, Kiln uses this order: + +1. The value in the job's `runs-on` label, if present. +2. The organization default, if set. +3. The Trunk default. + +So a job label can override a default per job. See +[Templates and regions](/kiln/actions/templates-and-regions). + + + Set an organization default template so most jobs need only a size. Keep the + per-job `template` option for jobs that need a different environment. + diff --git a/kiln/settings/limits-and-priority.mdx b/kiln/settings/limits-and-priority.mdx new file mode 100644 index 00000000..ec4f425a --- /dev/null +++ b/kiln/settings/limits-and-priority.mdx @@ -0,0 +1,34 @@ +--- +title: "Limits and priority" +description: "Set a CPU limit for CI, and mark the branches that run first when CI is busy." +groups: ["firewatch"] +--- + +{/* Generated in trunk-io/docs2 from apps/firewatch/docs in trunk-io/trunk-cloud. */} + +An organization admin sets how much CI your organization runs at once, and which +jobs run first when CI is busy. + +## CPU limit + +Your organization has a limit on the total CPUs that CI jobs use at once. When +jobs reach the limit, Kiln holds new jobs until CPUs free up. The held jobs start +when there is room. A job is not lost; it waits. + + + Ask the Trunk team to raise your CPU limit if your CI waits too often. + + +## Priority branches + +You can mark branches as priority. Jobs on those branches run first when CI is +busy. Kiln does not hold a priority job under load. + +Use priority branches for the branches that must stay fast, such as your default +branch or a release branch. + + + Priority changes the order of jobs. It does not raise the CPU limit. Under + heavy load, a priority job runs before other jobs, but the total CPUs still + stay under the limit. +