Skip to content
KiCI Docs

SDK reference

Reference documentation for @kici-dev/sdk. The reference is split across the per-topic pages below.

PageCovers
Coreworkflow(), job(), step() factory functions and step / job authoring patterns (bare functions, output chaining, needs, dynamic groups).
TriggersAll 23 trigger factories — GitHub events (pr, push, tag, comment, …), event triggers (kiciEvent, workflowComplete, workflowsFailedBatch, jobComplete), genericWebhook, schedule, lifecycle, plus branch-pattern semantics.
Rules, matrix, dynamic jobsrule(), skip(), matrix builds (static + dynamic), and dynamicJob() / dynamicGroup().
runsOnAll host fan-outrunsOnAll — fan one job out to every matching connected host, one pinned execution per host, with exact / glob / regex host selectors.
CachingCacheSpec, declarative cache on jobs/steps, imperative ctx.cache.restore() / ctx.cache.save(), immutable keys, restoreKeys prefix fallback, per-org + per-ref isolation.
Artifactsctx.artifacts — share named, durable build outputs between jobs of a run and download them from the run page.
Validation & eventsvalidateDag(), defineEvent(), event emission patterns.
RuntimeTypes index, StepContext, secrets, and fixtures.
Temp directoriesctx.mktemp() / ctx.mktempFile() — allocate job-scoped scratch dirs and files that are cleaned up automatically when the job ends.
Event payload referenceGenerated schema of the normalized event envelope passed to rules and dynamic functions.
Idempotent helpersidempotent(), idempotentStep(), and the check-mode-aware checkStep() — check / apply pattern with typed results on both the skipped and applied branches.
Wait-for helperswaitFor() and waitForStep() — poll a condition on an interval, run an optional success action, recover gracefully on timeout.
Parallel stepsparallel() — run independent steps concurrently within one job behind a join barrier, each as its own observable step, with failFast and maxParallel controls.

The @kici-dev/sdk package re-exports the entire surface from a single entry point. Pick what you need:

import { workflow, job, step, pr, push, rule, defineEvent } from '@kici-dev/sdk';

For the complete list of every named export (factory functions, triggers, rules, validation, hook factories, types), see the per-topic pages above.

@kici-dev/sdk/internal is not a supported surface

Section titled “@kici-dev/sdk/internal is not a supported surface”

The package also publishes an @kici-dev/sdk/internal subpath. It carries the runtime contract between the SDK and the KiCI agent. Those are the functions that install the maps a .result proxy reads, build the step context your workflow body receives, evaluate its rules, and expand its matrix. The agent drives all of it on your behalf.

It is not covered by semver and may change shape in any release. Do not import it from a workflow. Everything a workflow author needs is on the root entry point above, and none of the runtime contract is exported there.

See also

Section titled “See also”