KiCI blog

Use GitHub Actions minutes as burst capacity for your CI

Alberto Marchetti — Sat, 29 Aug 2026 00:00:00 GMT

Bursting CI usually means booting machines you own

You want CI capacity that grows when the queue backs up and shrinks when it drains. Today you pick between two costs. Reserve the machines and you pay for the peak all month, even at 3am when nothing runs. Or wire up a cloud-provisioning integration: an API to boot a VM, credentials to inject, a lifecycle to babysit, a reaper to make sure a crash doesn’t leave an instance billing you for a week.

Both cost you the same assumption: bursting means booting a server you own and operate. That assumption is the expensive part.

A KiCI agent is a process, not a server

Here’s what a KiCI agent is: a plain Node process that opens one outbound WebSocket to your orchestrator and runs the jobs it’s handed. In one-shot mode it runs a single job and exits. It needs a Node runtime, a network path out, and nothing else. It does not care what started it.

So “add capacity” doesn’t have to mean “boot a VM.” It can mean “ask something that can already run a process to run one.” And you have systems that do exactly that, sitting idle between builds: your CI runners.

KiCI’s event scaler is built for this. It makes no cloud calls of its own. When demand rises it emits a reserved kici.scaler.scale-up event; when an agent should go away it emits kici.scaler.scale-down. You consume those in a provisioning workflow you write in TypeScript, with the same kiciEvent() trigger you’d use for anything else. The workflow-driven autoscaling guide covers the event contract. What comes up, and how, is the one thing left open on purpose.

GitHub Actions as the pool

The pool most teams already have is GitHub Actions. Its runner queue is elastic, a run is already an ephemeral, one-shot sandbox (the exact shape of a scale-to-zero agent), and the minutes are free up to your plan’s quota on private repos, and free outright on public repos using standard runners.

Here’s the provisioning workflow. It subscribes to the scale-up event and dispatches a kici-agent.yml run in a GitHub repo:

import {
  workflow,
  job,
  step,
  kiciEvent,
  SCALER_EVENT_NAMES,
  ScalerScaleUpPayload,
} from '@kici-dev/sdk';

/** Must match the `name:` of the `event` scaler in your `scalers.yaml`. */
const SCALER_NAME = 'github-actions';

/** The one-shot runner workflow in your runner repo, and the ref to dispatch. */
const GH_WORKFLOW = 'kici-agent.yml';
const GH_REF = 'main';

export default workflow('github-actions-autoscale-provision', {
  on: [kiciEvent({ name: SCALER_EVENT_NAMES.scaleUp, match: { '$.scalerName': SCALER_NAME } })],
  jobs: [
    job('provision', {
      runsOn: ['default'],
      // Binds the `github-actions` context, which carries both the dispatch
      // token and this integration's two settings. Load-bearing: the job option
      // is `context`, and an unrecognised key is DROPPED at compile time rather
      // than rejected — so a typo here fails at run time on an unresolved
      // secret, never at compile time.
      context: 'github-actions',
      steps: [
        step('dispatch', async (ctx) => {
          const p = ScalerScaleUpPayload.parse(ctx.rawPayload);

          // Your runner repo, as `owner/repo`. Set it once on the context:
          //   kici-admin variable set <orgId> github-actions \
          //     GITHUB_RUNNER_REPO --value myorg/ci-runners
          // or replace the fallback below in your own copy.
          const runnerRepo = ctx.env.GITHUB_RUNNER_REPO ?? 'myorg/ci-runners';

          // Optional. A release tag holding a `kici-admin agent package` tarball
          // the runner installs instead of the published npm agent. Leave it
          // unset unless you pin exact builds or your runners cannot reach npm.
          const agentBundleRelease = ctx.env.GITHUB_AGENT_BUNDLE_RELEASE;

          const inputs: Record<string, string> = {
            claim_code: p.claimCode,
            orchestrator_url: p.orchestratorUrl,
            agent_id: p.agentId,
            labels: p.labels.join(','),
          };
          if (agentBundleRelease) inputs.agent_bundle_release = agentBundleRelease;

          const token = await ctx.secrets.get('GITHUB_DISPATCH_TOKEN');
          const res = await fetch(
            `https://api.github.com/repos/${runnerRepo}/actions/workflows/${GH_WORKFLOW}/dispatches`,
            {
              method: 'POST',
              headers: {
                Authorization: `Bearer ${token}`,
                Accept: 'application/vnd.github+json',
                'X-GitHub-Api-Version': '2022-11-28',
              },
              body: JSON.stringify({ ref: GH_REF, inputs }),
            },
          );
          // GitHub answers a successful dispatch with 204 and no body.
          if (!res.ok && res.status !== 204) {
            throw new Error(`dispatch failed: ${res.status} ${await res.text()}`);
          }
          ctx.log.info(`Dispatched ${GH_WORKFLOW} in ${runnerRepo} for agent ${p.agentId}`);
        }),
      ],
    }),
  ],
});

That’s the whole KiCI side. The step body speaks plain HTTP to GitHub’s REST API, with no SDK to install. Everything specific to “how a machine comes up” lives there; swap it and you’ve pointed KiCI at a different pool.

The run it dispatches is a normal GitHub Actions workflow. It installs the agent and runs it once:

on:
  workflow_dispatch:
    inputs:
      claim_code:
        description: Single-use claim code the agent exchanges for its token
        required: true
      orchestrator_url:
        description: Orchestrator WebSocket URL the agent connects back to
        required: true
      agent_id:
        description: Agent id the orchestrator correlates the spawn with
        required: true
      labels:
        description: Comma-separated label set the pending job needs
        required: false
        default: ''
      agent_bundle_release:
        description: >-
          Release tag in this repo holding a `kici-admin agent package` tarball.
          Leave empty to install the published agent from npm.
        required: false
        default: ''

jobs:
  agent:
    runs-on: ubuntu-latest
    # A one-shot agent registers, runs one job and exits, so a run that is still
    # alive after this long is wedged (an agent the orchestrator refused, a job
    # that never dispatched) and must release the runner rather than bill the
    # default six hours. Raise it if your jobs legitimately run longer.
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      # Default path: the published agent, from npm.
      - name: Set up Node.js
        if: ${{ inputs.agent_bundle_release == '' }}
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '24'
      - name: Install the KiCI agent
        if: ${{ inputs.agent_bundle_release == '' }}
        run: npm install -g kici-admin

      # Pinned path: a self-contained bundle your orchestrator produced with
      # `kici-admin agent package`. It vendors its own Node, so it needs no
      # setup-node. Use it to pin an exact agent build, or for runners that
      # cannot reach npm. Prepending it to PATH keeps the run step below uniform.
      - name: Install the KiCI agent (packaged bundle)
        if: ${{ inputs.agent_bundle_release != '' }}
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE: ${{ inputs.agent_bundle_release }}
        run: |
          gh release download "$RELEASE" --repo "$GITHUB_REPOSITORY" \
            --pattern 'kici-agent-linux-x64.tar.gz*' --clobber
          sha256sum -c kici-agent-linux-x64.tar.gz.sha256
          mkdir -p kici-agent-dist
          tar xzf kici-agent-linux-x64.tar.gz -C kici-agent-dist
          echo "$PWD/kici-agent-dist" >> "$GITHUB_PATH"

      - name: Run the one-shot KiCI agent
        env:
          KICI_ORCHESTRATOR_URL: ${{ inputs.orchestrator_url }}
          KICI_SCALER_CLAIM_CODE: ${{ inputs.claim_code }}
          KICI_AGENT_ID: ${{ inputs.agent_id }}
          KICI_LABELS: ${{ inputs.labels }}
          # Managed mode + zero idle timeout: register, run one job, exit.
          KICI_SCALER_MANAGED: '1'
          KICI_EXECUTION_MODE: bare-metal
          KICI_SCALER_IDLE_TIMEOUT: '0'
        run: exec kici-agent

The agent runs directly on the runner, installed with npm rather than wrapped in a container, so job steps that need Docker use the runner’s own daemon. If your runners can’t reach npm, or you want to pin an exact build, set agent_bundle_release to a release holding a kici-admin agent package tarball and it installs that instead. The bundle vendors its own Node, so that path skips the Node setup. KICI_SCALER_MANAGED and a zero KICI_SCALER_IDLE_TIMEOUT are the whole contract: register, run one job, exit.

And the scaler config that ties it together: an event scaler, no new backend type:

version: 1
scalers:
  - name: github-actions
    type: event
    maxAgents: 20
    # Repo identifiers, NOT workflow names: the reserved events are delivered
    # with `target.repos = provisioningTargets`, and the router filters
    # registrations by repo. A workflow name here matches no registration and
    # the scale-up reaches no subscriber at all.
    provisioningTargets:
      - myorg/infra
    labelSets:
      - labels: [github-actions]

Where each file lives

The pieces live in different places, and the GitHub repos do different jobs:

The workflow repo (myorg/infra) holds the provisioning and teardown workflows in .kici/workflows/. They’re ordinary workflows, not global ones. The scaler’s provisioningTargets names this repo, and KiCI delivers the scale-up and scale-down events only to workflows registered there. KiCI has to receive its pushes, like any repo it runs.
The runner repo (myorg/ci-runners) holds kici-agent.yml in .github/workflows/. Its Actions minutes are the ones you spend. KiCI never needs its pushes: the provisioning workflow dispatches runs in it through GitHub’s API.
scalers.yaml sits with your orchestrator, not in either repo.

Your application repos don’t change, apart from the label: a job that may wait in GitHub’s queue says runsOn: ['github-actions'].

The credential you can safely put in a dispatch input

There’s a real hazard hiding in “dispatch a workflow with inputs.” GitHub treats workflow_dispatch inputs as ordinary event data: the run reads them from github.event.inputs, and GitHub’s security guide says to mask any sensitive value that isn’t a GitHub secret. Put an agent token in an input, and one stray echo writes a live credential into the run’s log.

So KiCI never passes the token. The scale-up event carries a single-use claim code, and the agent redeems it itself, over the same WebSocket it has to open anyway, for a short-lived token that never leaves that connection. The claim code is safe to log: it’s one-time, short-lived, and useless once redeemed. Pass it through GitHub’s inputs, a cloud-init file, anywhere. The thing worth stealing never travels.

Teardown you get for free

The scary part of “boot compute on demand” is the instance nobody cleaned up. Here you mostly don’t have that problem: a GitHub Actions run ends when its one-shot agent exits, and GitHub caps every job on a hosted runner at 6 hours as a hard backstop. The run can’t outlive its job.

There’s still a teardown workflow, but it does less than the cloud version’s reaper. It only cancels a run GitHub has not yet marked finished, and only when the agent will never do useful work, because it never started or it went silent:

import {
  workflow,
  job,
  step,
  kiciEvent,
  SCALER_EVENT_NAMES,
  ScaleDownReason,
  ScalerScaleDownPayload,
} from '@kici-dev/sdk';

/** Must match the `name:` of the `event` scaler in your `scalers.yaml`. */
const SCALER_NAME = 'github-actions';
const GH_WORKFLOW = 'kici-agent.yml';

/**
 * The only two reasons that mean the run will never do useful work:
 *
 *   spawn-timeout      no agent ever registered against the spawn
 *   heartbeat-timeout  the agent registered, then went silent
 *
 * Every other reason is left alone. `shutdown` in particular is what a HEALTHY
 * one-shot agent emits when it exits after finishing its job — cancelling on it
 * would kill a run that is already succeeding. An unrecognised reason falls
 * through to doing nothing, which is always the safe default here: the run
 * reaps itself.
 */
export const CANCELABLE: ScaleDownReason[] = ['spawn-timeout', 'heartbeat-timeout'];

export default workflow('github-actions-autoscale-teardown', {
  on: [kiciEvent({ name: SCALER_EVENT_NAMES.scaleDown, match: { '$.scalerName': SCALER_NAME } })],
  jobs: [
    job('teardown', {
      runsOn: ['default'],
      // Binds the `github-actions` context. Required for BOTH halves: the
      // dispatch token this job reads, and `GITHUB_RUNNER_REPO` below — context
      // variables resolve only from the contexts a job binds, so an unbound
      // teardown reads `undefined` for the repo.
      context: 'github-actions',
      steps: [
        step('cancel-stranded-run', async (ctx) => {
          const p = ScalerScaleDownPayload.parse(ctx.rawPayload);
          if (!CANCELABLE.includes(p.reason)) {
            ctx.log.info(`teardown reason=${p.reason} agent=${p.agentId} action=skip`);
            return;
          }

          const runnerRepo = ctx.env.GITHUB_RUNNER_REPO ?? 'myorg/ci-runners';
          const token = await ctx.secrets.get('GITHUB_DISPATCH_TOKEN');
          const headers = {
            Authorization: `Bearer ${token}`,
            Accept: 'application/vnd.github+json',
            'X-GitHub-Api-Version': '2022-11-28',
          };

          // `kici-agent.yml` sets its `run-name` to `kici-agent {agent_id}`,
          // which is how a scale-down finds the run its agent belongs to. One
          // page bounds it for most pools: the run is at most one spawn-timeout
          // window old, so a pool creating fewer than 100 runs of this workflow
          // inside that window always finds it here. A busier pool needs
          // pagination. What decides is the age of the RUN — the list is newest
          // first — not how fast the teardown follows the scale-down.
          const listed = await fetch(
            `https://api.github.com/repos/${runnerRepo}/actions/workflows/${GH_WORKFLOW}/runs?per_page=100`,
            { headers },
          );
          if (!listed.ok) {
            throw new Error(`listing runs failed: ${listed.status} ${await listed.text()}`);
          }
          const body = (await listed.json()) as {
            workflow_runs: Array<{ id: number; name?: string; status: string }>;
          };
          const run = body.workflow_runs.find((r) => r.name === `kici-agent ${p.agentId}`);

          // Anything GitHub has not marked `completed` is still live — that
          // covers `queued` and `in_progress` plus the pre-start states
          // (`requested`, `waiting`, `pending`), which is exactly where a
          // spawn-timeout run sits. Listing the live states instead would
          // decline to cancel the case this workflow exists for.
          if (!run || run.status === 'completed') {
            ctx.log.info(
              `teardown reason=${p.reason} agent=${p.agentId} action=skip (no live run)`,
            );
            return;
          }

          const cancelled = await fetch(
            `https://api.github.com/repos/${runnerRepo}/actions/runs/${run.id}/cancel`,
            { method: 'POST', headers },
          );
          // 409 is GitHub refusing the cancel, most often because the run
          // finished between the list above and this call. A teardown the
          // orchestrator could not deliver is retried, so treating that as a
          // failure would fail the workflow forever over a run that is already
          // in the state the teardown wanted.
          if (cancelled.status === 409) {
            ctx.log.info(
              `teardown reason=${p.reason} agent=${p.agentId} action=skip ` +
                `(run ${run.id} not cancelable: 409, most often already completed)`,
            );
            return;
          }
          if (!cancelled.ok) {
            throw new Error(`cancel failed: ${cancelled.status} ${await cancelled.text()}`);
          }
          ctx.log.info(
            `teardown reason=${p.reason} agent=${p.agentId} action=cancel run=${run.id}`,
          );
        }),
      ],
    }),
  ],
});

For a job that already finished, there’s nothing to cancel: the run is gone. Compare that to a cloud VM, where teardown is a delete call you’d better not miss.

The trade-off: you inherit GitHub’s queue and limits

Compute you already pay for is a real win, and it comes with a real cost you should see clearly. When you borrow someone else’s pool, you inherit that pool’s guarantees. For GitHub Actions that means:

Queue latency becomes your scheduling latency. A dispatched run waits for a hosted runner before the job even starts, and GitHub discards a queued run that no hosted runner picks up within 45 minutes. If you need an agent up in under a second, this is the wrong pool.
The minutes are GitHub’s, and so are the prices. Past your plan’s included minutes, a private repo pays GitHub’s per-minute rate: $0.006 a minute for a standard Linux runner, as of September 2026.
Your fan-out ceiling is GitHub’s concurrency limit, not KiCI’s reservation math. Standard hosted runners run up to 20 concurrent jobs on Free, 60 on Team and 500 on Enterprise.
You get best-effort placement. The example asks for ubuntu-latest, with no say over instance class or region, and a GitHub incident is a KiCI capacity incident.

KiCI doesn’t paper over this. When a provision fails (GitHub down, dispatch rejected, minutes exhausted) the scaler reports the failure and backs off a pool that keeps failing, instead of hammering it. You see the problem; you don’t get a silent stall.

So this is a choice, and it’s per scaler. Latency-critical jobs point at a cloud scaler or a warm pool you keep hot. Bursty, tolerant work (nightly matrices, PR fan-out, background jobs that need to finish sometime) points at the GitHub pool. Same orchestrator, different label. You decide which jobs are allowed to wait in a queue.

The same pattern on GitLab CI, Nomad or a spare box

None of this is specific to GitHub. Look at what each piece needs:

What KiCI brings is fixed and engine-independent: noticing demand, minting the claim code, handing the pending job to whatever registers, spawn and idle timeouts, and the backoff when a pool keeps failing.
What you write is the one part that changes: the step body that asks your engine to start a process with a few env vars. For GitHub it’s a workflow_dispatch. For GitLab CI it’s a pipeline trigger. For Nomad it’s a batch job. For a spare box in the corner it’s a queued docker run.
What the agent needs is small and the same everywhere: a Node runtime, a way out to the orchestrator, and a handful of env vars.

Any system that can run a process on request is a burst pool for KiCI. GitHub Actions is the one almost everyone already pays for. And the trade-off carries over too: each engine you borrow brings its own queue and limits.

Set it up

Let your coding agent do it. Every step below is a file to write or a command to run, which is the kind of work a coding agent is good at. Give yours this post’s URL and ask it to set up a GitHub Actions burst pool by following these steps. For the SDK details, point it at llms.txt or pipe kici docs llm sdk into its context.

The steps use myorg/infra for the workflow repo and myorg/ci-runners for the runner repo. Every file shown above is in examples/github-actions-autoscale/, ready to copy.

Sign up and bring up an orchestrator. Create a free account at app.kici.dev and follow the 5-minute quickstart through Part 2, so pushes from your GitHub App reach the orchestrator.
Create the workflow repo. Create a repo such as myorg/infra and install the quickstart’s GitHub App on it, so KiCI receives its pushes. Clone it and run kici init in the clone. That creates .kici/, with the package.json that declares @kici-dev/sdk. Delete any starter workflow it adds that you don’t want to run.
Make the orchestrator reachable from GitHub’s runners. A hosted runner dials the orchestrator’s agent endpoint (/ws) from GitHub’s network, so expose that endpoint at an address the runners can reach, such as wss://ci.example.com/ws. If it differs from the orchestrator’s own KICI_ORCHESTRATOR_URL, set it as orchestratorUrl on the scaler entry in step 7.
Pick the agent that runs the provisioning workflow. The provisioning workflow runs on an agent too, and it can’t wait for the pool it’s growing. The quickstart’s scaler already spawns one: in both KiCI workflows, you’ll change runsOn: ['default'] to that scaler’s labels, ['linux', 'container'] for the Docker quickstart or ['linux', 'bare-metal'] for bare metal. Those agents keep their default roles, so they also pack the workflow’s source before the job runs.
Add the runner workflow to the runner repo. Commit kici-agent.yml to .github/workflows/kici-agent.yml on the runner repo’s default branch. GitHub dispatches only a workflow file that’s on the default branch. The provisioning workflow dispatches ref main, so change GH_REF in it if your default branch has another name.
Store the token in a github-actions context. Create a fine-grained GitHub token with Actions: read and write on the runner repo. Then, where you run kici-admin against your orchestrator, create the context, store the token in its scope, and point it at the runner repo:
```
kici-admin context create --org <orgId> --name github-actions
kici-admin secret set <orgId> github-actions GITHUB_DISPATCH_TOKEN --prompt
kici-admin context bind --org <orgId> --env github-actions --scope github-actions
kici-admin variable set <orgId> github-actions GITHUB_RUNNER_REPO --value myorg/ci-runners
```
Leave the context’s protection rules off. An approval hold on it would hold every scale-up, and the agents would never appear.
Declare the event scaler. Open the scalers.yaml the quickstart created: next to docker-compose.yaml for Docker, or ~/.config/kici/scalers.yaml for bare metal. Add the github-actions entry shown above under scalers:, next to the quickstart’s own. provisioningTargets is the workflow repo from step 2, written as owner/repo. Load it with kici-admin scaler reload. It checks the file and applies all of it or none of it, on the orchestrator it points at and every orchestrator connected to it, and prints what changed or why it refused the file. Here it prints added: github-actions.
Add the two KiCI workflows to the workflow repo. In the clone from step 2, save provision.workflow.ts as .kici/workflows/github-actions-provision.ts and teardown.workflow.ts as .kici/workflows/github-actions-teardown.ts. Make the runsOn change from step 4 in both. The workflow repo then looks like this:
```
myorg/infra/
└── .kici/
    ├── package.json
    ├── workflows/
    │   ├── github-actions-provision.ts
    │   └── github-actions-teardown.ts
    └── kici.lock.json          # written in the next step
```
Compile and push to the default branch. From the root of the clone:
```
kici compile
git add .kici/
git commit -m "ci: add GitHub Actions burst pool workflows"
git push origin main
```
KiCI registers the scale-up and scale-down subscriptions only from the default branch’s lock file, so push to that branch (main here). Until that push, a scale-up reaches no one. Confirm both workflows registered with kici-admin registration list --repo myorg/infra: it lists github-actions-autoscale-provision and github-actions-autoscale-teardown.
Send jobs to the pool and watch them. In any repo KiCI runs, give a job you’re happy to let wait in GitHub’s queue runsOn: ['github-actions'], and push it. That repo needs no other change. A kici-agent <agent-id> run appears in the runner repo’s Actions tab. It registers, runs the job, and finishes. If no run appears, the provisioning workflow’s own run shows the dispatch error, and kici-admin diagnose names the failure on the scaler:github-actions row.

The machine that runs a KiCI job can be anything that runs a process, and the TypeScript that brings it up is yours.

Make your org-wide pipeline wait for each repo's own tests

Alberto Marchetti — Wed, 19 Aug 2026 00:00:00 GMT

A shared pipeline and each repo’s tests end up racing

The org pipeline knows how to build and deploy. What it does not know is how any one repo tests itself: a service with a Postgres integration suite, a library with a fuzz run, a frontend with a Playwright pass. Those live in the repo, and they differ from repo to repo.

That leaves you two bad options. You let the repo’s own CI run independently, so the org’s deploy step and the repo’s tests fan out off the same push and race: the deploy can ship before the tests finish. Or you copy each repo’s test steps up into the org pipeline, and now the org pipeline is a pile of per-repo special cases that drifts the moment a repo changes how it tests.

The frame is right (one pipeline, every repo) but it has no extension point. The org owns the frame; each repo needs to fill in its own slot, and the frame needs to wait for it.

invokeSource: call each repo’s tests and wait

invokeSource is that extension point, and the global workflows guide covers it in full. A job in the org pipeline calls it, and instead of running steps on an agent, the job emits a named event at the repo that triggered the pipeline and waits for every workflow there that opted in. Each opted-in workflow that fires becomes a job in the org run’s own graph, so you watch the repo’s tests in the same run as the deploy, and the downstream jobs gate on them.

Here is the org side. The repo-tests job hands control back to the source repo, and deploy needs it, so the deploy runs only after the repo’s tests pass:

export default workflow('org-ci-with-repo-tests', {
  on: [push({ repos: ['myorg/*'], branches: ['main'] })],
  jobs: [
    // Hand control to the source repo: emit `org.repo-tests` there and gate on
    // every workflow that subscribes. Required by default.
    job('repo-tests', { invoke: invokeSource('org.repo-tests') }),
    // Ships only after the source repo's own tests reported success.
    job('deploy', {
      needs: ['repo-tests'],
      runsOn: ['kici:os:linux'],
      run: async ({ $ }) => {
        await $`./deploy.sh`;
      },
    }),
  ],
});

And here is a repo filling the slot. This workflow lives in an application repo, not the org pipeline. It subscribes to the org’s event with kiciEvent, so when the org pipeline invokes the repo, this runs and the gate waits for it:

export default workflow('repo-tests', {
  on: [kiciEvent({ name: 'org.repo-tests' })],
  jobs: [
    job('unit', {
      runsOn: ['kici:os:linux'],
      run: async ({ $ }) => {
        await $`pnpm test`;
      },
    }),
  ],
});

That’s the whole contract. The org names an event; a repo opts in by listening for it. Add the one file and your tests are in the org pipeline; the org pipeline never had to know they existed.

Required by default: a repo that forgot fails loud

Here is the part that matters at three in the morning. What happens when a repo never wired up its tests, with no subscriber listening for the event?

invokeSource is required by default. Zero subscribers is a failed gate, not a pass. The deploy job needs the gate, so it does not run. A repo that quietly dropped its test workflow does not sail through the org pipeline green; it stops, and you find out because the pipeline is red, not because production is.

This is the opposite of the racing setup, where a repo with no tests looks exactly like a repo whose tests happened to pass. Here, “no tests ran” is a distinct, loud outcome.

Opt out on purpose with `optional`

Required-by-default is the safe default, but some repos have nothing to run: a docs-only repo, a config repo. For those, the org pipeline sets optional: true on the gate:

job('repo-tests', { invoke: invokeSource('org.repo-tests', { optional: true }) });

Now zero subscribers is a green skip, and the downstream still runs. The difference is intent: with optional, “no tests” is a decision the org made, not a repo that forgot. You choose which repos are allowed to have nothing to say.

Decide per repo at runtime

The gate can also be generated at runtime. A DynamicJobFn runs with the source repo checked out, so it can read the repo and decide whether to invoke at all. This variant reads the repo’s package.json and adds the gate only for a repo that declares a ci:test script, so the org invokes each repo’s tests exactly where they exist:

const gateWhereTestsExist: DynamicJobFn = async ({ sourceRepo }) => {
  const root = sourceRepo?.path ?? '.';
  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
  const declaresTests = 'ci:test' in (pkg.scripts ?? {});
  // A repo that declares its own tests gets an invoke gate; one that does not is
  // left un-gated rather than failed.
  return declaresTests ? [job('repo-tests', { invoke: invokeSource('org.repo-tests') })] : [];
};

export default workflow('org-ci-matrix-repo-tests', {
  on: [push({ repos: ['myorg/*'], branches: ['main'] })],
  jobs: [gateWhereTestsExist],
});

This is plain TypeScript against the tree on disk, so the rule can be anything you can express in code: gate the repos that ship a Dockerfile, invoke a different event for a repo tagged one way versus another, read a repo-local config file and branch on it. The org pipeline decides per repo what to summon, and the repos decide what to answer with.

Reading the results

An invoked run can report outputs, and they cross back to the downstream job as ctx.needs['repo-tests'].result: coverage numbers, a build id, whatever the repo’s tests emit. Secret outputs stay masked and never cross the boundary, so a repo can report a token to its own steps without leaking it into the org pipeline. The org gets exactly what the repo chose to publish, and nothing it did not.

When you don’t need invokeSource

A single repo. A repo’s own workflow can already make its deploy job needs its test job. The extra hop through an event buys nothing.
Tests that are the same in every repo. If every repo runs npm test the same way, the global workflow can run those tests itself, with jobs generated per source repo. invokeSource earns its place when each repo tests itself differently.
A slow repo suite holds the org deploy. The gate waits for every run it summoned, and a run held for an approval waits as long as the hold lasts. Give the gate job a timeout, in milliseconds, so the wait is bounded; the guide shows it next to the other job options.

Set it up

The steps use the event name org.repo-tests from the snippets above.

Sign up and bring up an orchestrator. Create a free account at app.kici.dev and follow the 5-minute quickstart through Part 2, so KiCI receives your GitHub org’s events. Install the GitHub App it uses on the whole org, or on the workflow repo plus every repo the org pipeline’s repos: glob covers.
Set up global workflows. Follow the steps in the global-workflows post from step 2: switch global workflows on, and set up a workflow repo that holds the org pipeline.
Pick the event name. It’s the contract between the org and every repo, so choose one and keep it. Names that start with kici. or __ are reserved, and invokeSource() rejects them when you compile.
Add the gate to the org pipeline. In the workflow repo’s .kici/workflows/, add a job with invoke: invokeSource('org.repo-tests') and make every job that must wait for the tests needs it, as the first snippet does. Pass { optional: true } if some repos may have nothing to run. Give the gate job a timeout if a repo’s test run can be held for an approval.
Compile and push the org pipeline. Run kici compile, commit the workflow with .kici/kici.lock.json, and push to the workflow repo’s default branch.
Opt each repo in. In each application repo that should report its tests, run npx kici init if it has no .kici/ folder yet. Add a workflow that subscribes with kiciEvent({ name: 'org.repo-tests' }), like the second snippet. It’s an ordinary workflow in that repo, so it can bind the repo’s own contexts and secrets. Run kici compile, commit it with .kici/kici.lock.json, and push to that repo’s default branch. KiCI registers the subscription only from the default branch’s lock file, and until it does, the gate finds no subscriber in that repo.
Push to an opted-in repo and watch the run. Push to main in that repo. The org run shows the repo’s workflow as a job under repo-tests, and deploy starts only after it passes. A repo with no subscriber shows a failed repo-tests gate instead, or a green skip when the gate is optional.

Autoscale CI onto any cloud with a TypeScript workflow

Alberto Marchetti — Mon, 17 Aug 2026 00:00:00 GMT

Autoscaling CI usually waits on a driver for your cloud

You want your CI to burst onto cloud compute when the queue backs up, then give it back when it drains. The common autoscalers get there with a driver per cloud. GitLab Runner’s autoscaler talks to each provider through a separate fleeting plugin: AWS, Google Cloud and Azure officially, and others from the community. Buildkite ships an Elastic CI Stack per cloud. Each driver is provider SDK code that somebody has to write, test and keep current as the provider’s API moves.

If your cloud isn’t on the list, you wait for someone to build the driver. If it is, you inherit whatever the driver’s authors decided about instance types, images and lifecycle, and you configure around it. Your image, your network and your budget all sit behind another team’s release cycle.

The event scaler hands provisioning to your workflow

KiCI’s scaler has an event backend that performs no cloud calls of its own. When demand rises, its spawn() emits a reserved kici.scaler.scale-up event; when an instance should go away, destroy() emits kici.scaler.scale-down. Those are ordinary KiCI custom events, and you consume them with the same kiciEvent() trigger you’d use for anything else, in a provisioning workflow you write in TypeScript. The workflow-driven autoscaling guide covers the whole contract.

So “cloud autoscaling” stops being “which drivers ship this quarter” and becomes “write a workflow.” KiCI keeps the hard, generic parts: demand detection, capacity caps, reservations, dispatching the pending job to the new machine, spawn timeouts, idle and heartbeat teardown. It leaves one thing open on purpose: how a machine comes up. That’s the extension point. Plug in any cloud’s API there and it works, with no driver required, so KiCI ships zero cloud SDK code and you’re never limited to a supported list.

The credential handoff is built for this. The scale-up event carries a single-use claim code, not a token. Your workflow forwards that code into the instance’s cloud-init, and the agent exchanges it for its own short-lived token once it boots. The token is minted inside the machine that uses it, and never transits provisioning or the persisted event log at all.

Writing the provisioning workflow

Here’s the reference provisioning workflow. It subscribes to the scale-up event, forwards the single-use claim code into a cloud-init, and boots a labelled instance whose agent claims its own token and registers under the scaler-chosen agentId. This one targets Hetzner; for another cloud, swap the boot call for that cloud’s API and keep the shape.

import {
  workflow,
  job,
  kiciEvent,
  buildAgentCloudInit,
  SCALER_EVENT_NAMES,
  ScalerScaleUpPayload,
} from '@kici-dev/sdk';

const SCALER_NAME = 'hetzner';
/** Hard lifetime cap for a provisioned instance (teardown layer L2). */
const MAX_LIFETIME_MINUTES = 30;

export default workflow('hetzner-autoscale-provision', {
  on: [kiciEvent({ name: SCALER_EVENT_NAMES.scaleUp, match: { '$.scalerName': SCALER_NAME } })],
  jobs: [
    job('provision', {
      runsOn: ['default'],
      // Bind the context whose scope holds the credential this job reads.
      // Without it `ctx.secrets` resolves nothing: the job option is `context`,
      // and an unrecognised key is dropped at compile time rather than
      // rejected, so the step would fail on a missing secret at run time.
      context: 'hetzner-autoscale',
      run: async (ctx) => {
        const payload = ScalerScaleUpPayload.parse(ctx.rawPayload);

        // Forward the single-use claim code into cloud-init; the agent claims
        // its own token in-instance, so the token never transits provisioning.
        const userData = buildAgentCloudInit(
          {
            claimCode: payload.claimCode,
            agentId: payload.agentId,
            orchestratorUrl: payload.orchestratorUrl,
            labels: payload.labels,
          },
          {
            maxLifetimeMinutes: MAX_LIFETIME_MINUTES,
            // Container delivery starts the agent with `docker run`, and the
            // stock `debian-12` image below ships no Docker — so install it.
            // Drop this line when your image already carries Docker.
            deliveryMode: 'container',
            packages: ['docker.io'],
            agentEnv: e2eAgentEnv(ctx.env),
          },
        );

        const token = await ctx.secrets.get('HETZNER_API_TOKEN');
        const client = new HetznerClient(token);
        const { id } = await client.createServer({
          name: `kici-agent-${payload.agentId}`,
          // A current-generation shared-vCPU type available in the region below.
          server_type: 'cpx12',
          image: 'debian-12',
          user_data: userData,
          // Every teardown layer keys off these labels.
          labels: {
            'kici-managed': 'hetzner-autoscale',
            'kici-agent-id': payload.agentId,
            'kici-scaler': SCALER_NAME,
            ...e2eServerLabels(ctx.env),
          },
        });

        ctx.log.info(`Provisioned Hetzner server ${id} for agent ${payload.agentId}`);
      },
    }),
  ],
});

Everything provider-specific lives in the run body: the instance type, the image, the labels, the API call. HetznerClient here is a thin wrapper over Hetzner’s REST API; the copy in the guide makes the same calls with fetch, so it needs nothing installed. The KiCI-specific parts are the kiciEvent trigger, the payload parse, and the buildAgentCloudInit call. There’s no backend to register and no plugin to install. Supporting a new cloud isn’t a feature request; it’s a new workflow you write today.

Where the provisioning workflows live

The provisioning and teardown workflows are ordinary workflows, not global ones. They live in one repo you pick, and the scaler’s provisioningTargets names it. KiCI delivers the scale-up and scale-down events only to workflows registered in that repo, so a kiciEvent subscription somewhere else never boots a server.

A dedicated infra repo is the tidy choice: the provisioning code and its reviews stay in one place, and your application repos don’t change at all. A job that wants a Hetzner machine says runsOn: ['hetzner'], and that’s it. Here’s the whole infra repo:

myorg/infra/
└── .kici/
    ├── package.json            # declares @kici-dev/sdk (kici init writes it)
    ├── workflows/
    │   ├── hetzner-provision.ts
    │   └── hetzner-teardown.ts
    └── kici.lock.json          # written by kici compile

Two things make the repo live. KiCI has to receive its pushes, and the two workflows have to reach its default branch, because event triggers register only from the default branch’s lock file. The setup steps below cover both.

Teardown that can’t leak a machine

The scary part of “boot a cloud instance on demand” is the one you don’t see: the instance that doesn’t get cleaned up when something crashes mid-run, quietly billing you for a week. So teardown doesn’t rely on any single path succeeding.

The scale-down event fires the mirror-image teardown workflow, which deletes the servers for the scaled-down agent by label:

import {
  workflow,
  job,
  kiciEvent,
  SCALER_EVENT_NAMES,
  ScalerScaleDownPayload,
} from '@kici-dev/sdk';

const SCALER_NAME = 'hetzner';

export default workflow('hetzner-autoscale-teardown', {
  on: [kiciEvent({ name: SCALER_EVENT_NAMES.scaleDown, match: { '$.scalerName': SCALER_NAME } })],
  jobs: [
    job('teardown', {
      runsOn: ['default'],
      // Bind the context whose scope holds the credential this job reads.
      // Without it `ctx.secrets` resolves nothing: the job option is `context`,
      // and an unrecognised key is dropped at compile time rather than
      // rejected, so the step would fail on a missing secret at run time.
      context: 'hetzner-autoscale',
      run: async (ctx) => {
        const payload = ScalerScaleDownPayload.parse(ctx.rawPayload);

        const token = await ctx.secrets.get('HETZNER_API_TOKEN');
        const client = new HetznerClient(token);

        const servers = await client.listByLabel(`kici-agent-id==${payload.agentId}`);
        if (servers.length === 0) {
          ctx.log.info(
            `No Hetzner server found for agent ${payload.agentId}; nothing to tear down`,
          );
          return;
        }
        for (const server of servers) {
          await client.deleteServer(server.id);
          ctx.log.info(`Deleted Hetzner server ${server.id} for agent ${payload.agentId}`);
        }
      },
    }),
  ],
});

That’s the happy path. Underneath it, the instance also shuts itself down: the cloud-init bakes in a hard lifetime cap that powers the machine off once it expires, so a machine that loses contact with the orchestrator still stops on its own. And every resource is labelled at creation (kici-managed=hetzner-autoscale), which lets a small reaper run on a timer and delete every labelled machine older than its TTL. The reaper is the backstop for the cases nothing else covers (a hard kill, a crashed orchestrator, a rebooted host) because it depends on nothing but the label and the clock. A leaked instance is measured in minutes, not invoices.

The reaper is a dependency-free script plus the thin API client it calls, published as an example you can copy. Its core lists the labelled servers and deletes the ones past the TTL:

/**
 * Delete servers older than the TTL. A delete 404 (already gone) counts as a
 * success. A delete that fails is recorded and the run moves on, so one server
 * Hetzner refuses to delete never shields the servers listed after it.
 */
export async function reap(client: ReapableClient, opts: ReapOptions): Promise<ReapResult> {
  // An empty selector lists every server in the project, so only an explicit
  // whole-project sweep may send one.
  if (!opts.sweepWholeProject && opts.managedLabel.trim() === '') {
    throw new Error('reap: managedLabel is empty; set sweepWholeProject to sweep every server');
  }
  const selector = opts.sweepWholeProject ? '' : opts.managedLabel;
  const servers = await client.listByLabel(selector);
  const cutoff = opts.now() - opts.olderThanMs;

  const result: ReapResult = { deleted: 0, failed: [] };
  for (const server of servers) {
    const createdMs = Date.parse(server.created);
    // A server whose timestamp cannot be parsed is left alone (fail-safe: never
    // delete something we cannot age).
    if (Number.isNaN(createdMs) || createdMs >= cutoff) continue;
    try {
      await client.deleteServer(server.id);
      result.deleted += 1;
    } catch (err) {
      const error = err instanceof Error ? err.message : String(err);
      result.failed.push({ id: server.id, name: server.name, error });
    }
  }
  return result;
}

When you don’t need a provisioning workflow

One host, or a fixed pool of machines. The built-in container scaler starts a one-shot agent container when a job arrives and removes it when the job ends. There’s no workflow to write, and it’s the backend most setups start with.
You’d rather not own the provisioning code. With the event scaler, the provisioning workflow, the teardown workflow and the reaper are yours. When your cloud’s API changes, you update them.
Jobs that can’t wait for a machine to boot. A cloud instance has to boot and start the agent before the job runs, so a queued job waits for that. A warm pool keeps ready agents for a label set, at the cost of paying for them while they sit idle.

Set it up

Let your coding agent do it. Every step below is a file to write or a command to run, which is the kind of work a coding agent is good at. Give yours this post’s URL and ask it to set up a Hetzner event scaler (or one for your own cloud) by following these steps. For the SDK details, point it at llms.txt or pipe kici docs llm sdk into its context.

The copy-ready provisioning and teardown workflows are in the workflow-driven autoscaling guide; they read their token as HETZNER_API_TOKEN from a hetzner-autoscale context. Another cloud follows the same steps with its own API calls.

Sign up and bring up an orchestrator. Create a free account at app.kici.dev and follow the 5-minute quickstart through Part 2, so pushes from your GitHub App reach the orchestrator. You also need a Hetzner Cloud project.
Create the repo that holds the provisioning workflows. Create a repo such as myorg/infra and install the quickstart’s GitHub App on it, so KiCI receives its pushes. Clone it and run kici init in the clone. That creates .kici/, with the package.json that declares @kici-dev/sdk. Delete any starter workflow it adds that you don’t want to run.
Make the orchestrator reachable from your instances. Each instance’s agent dials the orchestrator’s agent endpoint (/ws) from the cloud network, so expose that endpoint where the instances can reach it. If the address differs from the orchestrator’s own KICI_ORCHESTRATOR_URL, set it as orchestratorUrl on the scaler entry in step 6.
Pick the agent that runs the provisioning workflow. The provisioning workflow runs on an agent too, and it can’t wait for the pool it’s growing. The quickstart’s scaler already spawns one: in both workflows, you’ll change runsOn: ['default'] to that scaler’s labels, ['linux', 'container'] for the Docker quickstart or ['linux', 'bare-metal'] for bare metal. Those agents keep their default roles, so they also pack the workflow’s source before the job runs.
Store the cloud token in a context. Create a Read & Write API token in the Hetzner project. Then, where you run kici-admin against your orchestrator, create the context, store the token in its scope, and bind the two:
```
kici-admin context create --org <orgId> --name hetzner-autoscale
kici-admin secret set <orgId> hetzner-autoscale HETZNER_API_TOKEN --prompt
kici-admin context bind --org <orgId> --env hetzner-autoscale --scope hetzner-autoscale
```
Leave the context’s protection rules off. An approval hold on it would hold every scale-up, and the agents would never appear.
Declare the event scaler. Open the scalers.yaml the quickstart created: next to docker-compose.yaml for Docker, or ~/.config/kici/scalers.yaml for bare metal. Add a hetzner entry under scalers:, next to the quickstart’s own. provisioningTargets is the repo from step 2, written as owner/repo, and the label set is what your jobs will ask for:
```
scalers:
  # ... the quickstart's scaler stays here ...
  - name: hetzner
    type: event
    maxAgents: 10
    provisioningTargets:
      - myorg/infra
    labelSets:
      - labels: [hetzner]
```
Load it with kici-admin scaler reload. It checks the file and applies all of it or none of it, on the orchestrator it points at and every orchestrator connected to it, and prints what changed or why it refused the file. Here it prints added: hetzner.
Add the two workflows to the repo. In the clone from step 2, save the guide’s provisioning workflow as .kici/workflows/hetzner-provision.ts and its teardown workflow as .kici/workflows/hetzner-teardown.ts. Make the runsOn change from step 4 in both. The provisioning workflow starts the agent with docker run and installs docker.io on the stock debian-12 image; drop that packages line if you boot an image that already has Docker.
Compile and push to the default branch. From the root of the clone:
```
kici compile
git add .kici/
git commit -m "ci: add Hetzner autoscaling workflows"
git push origin main
```
KiCI registers the scale-up and scale-down subscriptions only from the default branch’s lock file, so push to that branch (main here). Until that push, a scale-up reaches no one. Confirm both workflows registered with kici-admin registration list --repo myorg/infra: it lists hetzner-autoscale-provision and hetzner-autoscale-teardown.
Schedule the reaper. Copy reap.ts and hetzner-client.ts from examples/hetzner-autoscale/ into one directory on a host that isn’t one of the pool’s servers and has Node.js 22.18 or later. Put a project token in HCLOUD_TOKEN, set KICI_HETZNER_REAP_TTL_MIN above your longest job, and run node reap.ts from a timer every few minutes. The example’s README has a systemd service and timer to copy, and the teardown and reaper runbook covers the TTL to pick and the alerts to set on it.
Send a job to the pool and watch it. In any repo KiCI runs, give a job runsOn: ['hetzner'] and push it. That repo needs no other change. A kici-agent-<agent-id> server appears in the Hetzner console, its agent registers and runs the job, and the teardown workflow deletes the server once the agent goes idle. If no agent registers, the provisioning workflow’s own run shows the API error, and kici-admin diagnose names the failure on the scaler:hetzner row.

The guide also covers the event contract, the buildAgentCloudInit options, and the AWS variant of the same workflow.

Run one CI pipeline across every repo in your org

Alberto Marchetti — Fri, 14 Aug 2026 00:00:00 GMT

Say you run forty repositories and you want the same test-and-build policy on all of them. The usual answer is to factor the shared steps into a reusable unit, then go to each of the forty repos and add a file that calls it. A GitHub Actions workflow calls a reusable workflow with uses:, a GitLab pipeline pulls shared YAML in with include:, and a Buildkite pipeline adds plugins to its own steps. The shared logic lives in one place, but every repo still opts in by carrying a file that points at it.

That’s forty pull requests to roll out a policy, forty more to change it, and forty chances for a repo to drift out of sync or never adopt it at all.

Some paid plans can push jobs from the top, as a compliance feature. GitLab Ultimate’s pipeline execution policies enforce CI jobs on projects, even ones with no CI file. GitHub rulesets can require a workflow from a central repo to pass before a pull request merges. Outside those settings, sharing CI still means one file per repo.

Global workflows: one repo pushes CI to all of them

A KiCI global workflow turns this around. One workflow repo declares the pipeline, its trigger carries a repos: glob, and the orchestrator runs it on events from every matching repo in the org. Nothing is added to the source repos: no file, no reference, no opt-in commit. You change the policy in one place, and it’s live everywhere on the next push.

The guardrails are built for that blast radius. Global workflows stay off until the orchestrator’s operator switches them on. Each org then governs them on two independent axes: an allow-list of which repos may author org-wide automation, and a deny-list of which source repos may trigger it. Secrets follow the same logic. A global job binds contexts one job at a time, and only the jobs that ask for them get them. The context rules are checked as the workflow repo’s, not the repo that pushed, so a context you limited to another repo stays out of reach of your ci-pipelines repo. Here’s the catch: a job that binds a context also runs whatever the source repo’s code does, so keep the source repo’s npm install and tests in jobs that bind nothing, and save the secrets for the jobs that publish or deploy. If a global workflow fires on pull requests, set minimumTrust on the contexts it uses, so a fork’s pull request waits for a human before it gets anywhere near them.

One pipeline for every repo would be a blunt tool if it ran the same way everywhere. It doesn’t have to: a global workflow can adapt to each repo, at three levels, from a one-line declarative gate to jobs generated from the repo.

Skip the repos that don’t need it with a content filter

The cheapest adaptivity is declarative. A requires content filter tells the orchestrator to dispatch the workflow only for repos whose files match a condition — here, repos whose package.json declares a ci:test script. A repo without that script is dropped before any agent is dispatched, so you spend zero compute on repos that opted out by not having the script.

export default workflow('org-ci-test', {
  on: [
    push({
      repos: ['myorg/*'],
      branches: ['main'],
      requires: [{ file: 'package.json', exists: ["$.scripts['ci:test']"] }],
    }),
  ],
  jobs: [
    job('test', {
      runsOn: 'kici:os:linux',
      steps: [
        step('ci-test', async ({ $ }) => {
          await $`pnpm run ci:test`;
        }),
      ],
    }),
  ],
});

Because the orchestrator evaluates this filter from file contents alone, it never starts an agent for a non-matching repo. It’s the right tool when the gate is a simple “does this repo have X” question.

Decide per repo with a TypeScript predicate

When the decision needs more than a JSON-path check, a workflow-level filter predicate runs on an evaluating agent with the source repo checked out. It’s plain TypeScript with the tree on disk, so it can inspect anything. This one runs the build pipeline only for repos that ship both a Dockerfile and a ci:build script.

export default workflow('org-ci-build', {
  on: [push({ repos: ['myorg/*'], branches: ['main'] })],
  filter: async ({ sourceRepo }) => {
    const root = sourceRepo.path;
    if (!existsSync(join(root, 'Dockerfile'))) return false;
    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
    return typeof pkg?.scripts?.['ci:build'] === 'string';
  },
  jobs: [
    job('build', {
      runsOn: 'kici:os:linux',
      steps: [
        step('ci-build', async ({ $ }) => {
          await $`pnpm run ci:build`;
        }),
      ],
    }),
  ],
});

The predicate reads the source repo through sourceRepo.path and returns a boolean. Unlike the content filter, the logic is arbitrary, and it works with any provider that can clone the repo.

Generate the jobs from each repo’s own scripts

The most expressive level generates the jobs at runtime from the repo’s own state. This workflow reads each source repo’s package.json and emits one job per ci:* script it finds, so every repo runs exactly the CI it declares, all defined once, centrally.

const perScript: DynamicJobFn = async ({ sourceRepo }) => {
  const root = sourceRepo?.path ?? '.';
  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
  const ciScripts = Object.keys(pkg.scripts ?? {}).filter((s) => s.startsWith('ci:'));
  return ciScripts.map((name) =>
    job(name.replace(':', '-'), {
      runsOn: 'kici:os:linux',
      steps: [
        step('run', async ({ $ }) => {
          await $`pnpm run ${name}`;
        }),
      ],
    }),
  );
};

export default workflow('org-ci-matrix', {
  on: [push({ repos: ['myorg/*'], branches: ['main'] })],
  jobs: [perScript],
});

A static YAML matrix lists its entries up front. Here the set of jobs is computed from the repository in front of you, in real code. A repo with ci:lint, ci:test and ci:build gets three jobs; a repo with one gets one, with no configuration in the source repos and no fan-out you had to list by hand.

When a global workflow is the wrong tool

Repos that have little in common. If every repo builds and deploys in its own way, one shared pipeline turns into a pile of per-repo branches. Keep per-repo workflows there, and use a global workflow for the policy that’s the same everywhere: lint, a security scan, a license check.
One bad change breaks CI on every repo at once. That’s the other side of changing the policy in one place. Roll a change out on a narrow repos: glob first, such as a single repo named in full, then widen it. The narrowing guide covers the other ways to limit where a global workflow runs.

Set it up

The steps call the repo that holds the org’s pipelines the workflow repo, myorg/ci-pipelines.

Sign up and bring up an orchestrator. Create a free account at app.kici.dev and follow the 5-minute quickstart through Part 2, so an orchestrator is running and receives your GitHub org’s events. Install the GitHub App it uses on the whole org, or on the workflow repo plus every repo your repos: glob should cover.
Switch global workflows on. The orchestrator’s operator runs kici-admin cluster-settings set --global-workflows-enabled true. The switch is off by default, and while it’s off KiCI doesn’t register repos: workflows at all. Turn it on before step 5’s push, or push again after.
Set up the workflow repo. Run npx kici init in myorg/ci-pipelines if it has no .kici/ folder yet. To keep other repos from shipping org-wide automation, add it under Settings → Global workflows → Allowed author repos in the dashboard.
Write the workflow. Copy the level you need into the workflow repo’s .kici/workflows/ and change myorg/* to your org. None of the three examples needs a secret. If you add a job that does, bind the context on that job alone and keep the source repo’s install and test steps in jobs that bind nothing. Then limit the context to the workflow repo, so no source repo can bind it from its own workflows: kici-admin context set-policy --org <org-id> --env <context> --repo-patterns '["myorg/ci-pipelines"]'. If the workflow also fires on pull requests, add --minimum-trust trusted.
Compile and push to the default branch. Run kici compile, commit the workflow with .kici/kici.lock.json, and push to the workflow repo’s default branch. KiCI registers global workflows only from that branch’s lock file, so a push to a feature branch changes nothing yet.
Push to a covered repo and watch the run. Push to main in any repo the glob matches. The run shows up in the dashboard under that source repo, with a Defined in row naming the workflow repo. If nothing runs, kici-admin registration list shows whether the workflow registered, and the troubleshooting table maps each symptom to its cause.

That’s one pipeline on every repo in the org, with nothing to merge into any of them.

KiCI blog

Use GitHub Actions minutes as burst capacity for your CI

Bursting CI usually means booting machines you own

A KiCI agent is a process, not a server

GitHub Actions as the pool

Where each file lives

The credential you can safely put in a dispatch input

Teardown you get for free

The trade-off: you inherit GitHub’s queue and limits

The same pattern on GitLab CI, Nomad or a spare box

Set it up

Make your org-wide pipeline wait for each repo's own tests

A shared pipeline and each repo’s tests end up racing

invokeSource: call each repo’s tests and wait

Required by default: a repo that forgot fails loud

Opt out on purpose with optional

Decide per repo at runtime

Reading the results

When you don’t need invokeSource

Set it up

Autoscale CI onto any cloud with a TypeScript workflow

Autoscaling CI usually waits on a driver for your cloud

The event scaler hands provisioning to your workflow

Writing the provisioning workflow

Where the provisioning workflows live

Teardown that can’t leak a machine

When you don’t need a provisioning workflow

Set it up

Run one CI pipeline across every repo in your org

Sharing CI today means a file in every repo

Global workflows: one repo pushes CI to all of them

Skip the repos that don’t need it with a content filter

Decide per repo with a TypeScript predicate

Generate the jobs from each repo’s own scripts

When a global workflow is the wrong tool

Set it up

Opt out on purpose with `optional`