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. +