# sparkwing -- v0.56.0 (latest)

> Self-hosted CI/CD platform with Go-defined pipelines, agent-friendly CLI, and embedded docs. This file lists the docs for v0.56.0 for AI agents that want to fetch directly. Links below point at raw markdown; the same page rendered as HTML lives at the .md-less URL with a trailing slash.

## Docs

- [Local admission policy](https://sparkwing.dev/docs/admission.md): Sparkwing's admission daemon decides when work may consume CPU and memory on one machine. It does not assess job risk. Risk declarations and approvals remain deterministic pipeline contracts and are unaffected by admission mode.
- [HTTP API reference](https://sparkwing.dev/docs/api-reference.md): Every route the controller and logs service register, with the scope each requires, generated from the routing code. All paths are under the `/api/v1` base (webhook and `/metrics` excepted). Scope enforcement and the token model are in [auth.md](auth.md); `admin` is the superset that satisfies any scope check. `public` routes run with no bearer check (the GitHub webhook is HMAC-verified instead); `authenticated` routes take any valid bearer and check no further scope.
- [Controller HTTP API](https://sparkwing.dev/docs/api.md): The controller and the logs service expose HTTP APIs under the `/api/v1` base path. The CLI, runners, the dashboard, and pipelines' cross-run refs are all clients. Responses are JSON.
- [Architecture](https://sparkwing.dev/docs/architecture.md): **This page describes the production deployment** - the sparkwing stack running in a shared Kubernetes cluster, where webhooks arrive from GitHub, a team looks at a central dashboard, and runners are pooled for work.
- [Node artifacts](https://sparkwing.dev/docs/artifacts.md): Artifacts move **files** between nodes. A producer node declares the files it emits; a consumer node declares which producers it draws from, and the orchestrator stages those files into the consumer's workspace before it runs. The transfer is explicit and content-addressed: a consumer never reaches into another node's working directory, and the files it receives are an immutable snapshot of what the producer published.
- [Authentication + authorization](https://sparkwing.dev/docs/auth.md): Sparkwing uses a shared-secret bearer token model with typed principals and per-endpoint scope annotations.
- [Authoring idiomatic pipelines](https://sparkwing.dev/docs/authoring-pipelines.md): A pipeline's `Plan` method and each job's `Work` method build the DAG. Plan inspection and execution must produce the same structure. Put I/O and host-dependent decisions in registered job or step callbacks, which execute after dispatch and may repeat on retry.
- [Storage backends](https://sparkwing.dev/docs/backends.md): Backends are configured per profile, not in a separate file. A profile declares four persistence surfaces plus how to reach a controller:
- [Build Caching](https://sparkwing.dev/docs/build-caching.md): How sparkwing makes Docker builds fast, and where the time actually goes.
- [Caching](https://sparkwing.dev/docs/caching.md): Sparkwing caches at four levels:
- [ci-embedded mode](https://sparkwing.dev/docs/ci-embedded.md): Run sparkwing pipelines **inside** an existing CI job (GitHub Actions, Buildkite, GitLab CI, CircleCI, ...) without standing up a sparkwing cluster. State, logs, and artifacts go to S3-compatible storage so a remote dashboard can follow the run live and replay it after the CI VM exits.
- [CLI reference: sparkwing cache](https://sparkwing.dev/docs/cli-cache.md): Every `sparkwing cache` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing cloud](https://sparkwing.dev/docs/cli-cloud.md): Every `sparkwing cloud` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing cluster](https://sparkwing.dev/docs/cli-cluster.md): Every `sparkwing cluster` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing commands](https://sparkwing.dev/docs/cli-commands.md): Every `sparkwing commands` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing completion](https://sparkwing.dev/docs/cli-completion.md): Every `sparkwing completion` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing configure](https://sparkwing.dev/docs/cli-configure.md): Every `sparkwing configure` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing crons](https://sparkwing.dev/docs/cli-crons.md): Every `sparkwing crons` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing daemon](https://sparkwing.dev/docs/cli-daemon.md): Every `sparkwing daemon` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing debug](https://sparkwing.dev/docs/cli-debug.md): Every `sparkwing debug` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing docs](https://sparkwing.dev/docs/cli-docs.md): Every `sparkwing docs` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing doctor](https://sparkwing.dev/docs/cli-doctor.md): Every `sparkwing doctor` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing examples](https://sparkwing.dev/docs/cli-examples.md): Every `sparkwing examples` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing fleet](https://sparkwing.dev/docs/cli-fleet.md): Every `sparkwing fleet` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing info](https://sparkwing.dev/docs/cli-info.md): Every `sparkwing info` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing pipeline](https://sparkwing.dev/docs/cli-pipeline.md): Every `sparkwing pipeline` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing profile](https://sparkwing.dev/docs/cli-profile.md): Every `sparkwing profile` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing queue](https://sparkwing.dev/docs/cli-queue.md): Every `sparkwing queue` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference](https://sparkwing.dev/docs/cli-reference.md): Every `sparkwing` command, flag, and argument, generated from the CLI's own command registry and split into one page per top-level command group. For the conceptual overview -- which binaries exist, the flag-naming rule, and what to reach for when -- see [cli.md](cli.md).
- [CLI reference: sparkwing repos](https://sparkwing.dev/docs/cli-repos.md): Every `sparkwing repos` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing run](https://sparkwing.dev/docs/cli-run.md): Every `sparkwing run` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing runs](https://sparkwing.dev/docs/cli-runs.md): Every `sparkwing runs` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing secrets](https://sparkwing.dev/docs/cli-secrets.md): Every `sparkwing secrets` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing serve](https://sparkwing.dev/docs/cli-serve.md): Every `sparkwing serve` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing update](https://sparkwing.dev/docs/cli-update.md): Every `sparkwing update` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI reference: sparkwing version](https://sparkwing.dev/docs/cli-version.md): Every `sparkwing version` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md).
- [CLI Reference](https://sparkwing.dev/docs/cli.md): Sparkwing ships a single `sparkwing` binary. This page is a map of what each command group is *for*; the complete, auto-generated listing of every command, flag, and argument lives in [cli-reference.md](cli-reference.md), one `cli-<group>.md` page per command group (offline: `sparkwing docs read --topic cli-reference`, or `--topic cli-<group>` for one group). Treat that generated reference as authoritative -- when this page and it disagree, it wins.
- [Config reference](https://sparkwing.dev/docs/config-reference.md): Reference tables for selected `.sparkwing/sparkwing.yaml` structs, generated from the Go structs the config parser enforces. `Required` reflects whether the field may be omitted. See [storage backends](backends.md) for profiles and [spark libraries](sparks.md) for library configuration.
- [Crons](https://sparkwing.dev/docs/crons.md): Sparkwing runs a pipeline on a cadence from the machine you arm, with no cluster and no resident process of its own. A repository declares the cadence; one host evaluates it. A repository can also declare a cadence for a controller to evaluate, which the same commands push and inspect with `--profile`; see [Controller schedules](#controller-schedules).
- [Deployment modes](https://sparkwing.dev/docs/deployment-modes.md): Two paths carry a reader: **Local** and **Sparkwing Cloud**. [Getting started](getting-started.md) walks both. This page is the storage-and-coordination taxonomy underneath them, for a team that hosts its own state, cache, or controller.
- [Deployment](https://sparkwing.dev/docs/deployment.md): Sparkwing is unopinionated about how your pipelines deploy. It provides the infrastructure - controller, runners, cache, logs - and your pipeline code decides what to do with it.
- [Fast builds: best practices](https://sparkwing.dev/docs/fast-builds.md): A living checklist of things that make sparkwing pipelines iterate fast. These emerged from measuring real iterations (touch a file, rebuild, redeploy, observe running) and watching where the time went.
- [Getting Started](https://sparkwing.dev/docs/getting-started.md): ## Two paths
- [Cache (Gitcache)](https://sparkwing.dev/docs/gitcache.md): sparkwing-cache is sparkwing's in-cluster git cache, blob store, and package proxy. It mirrors repositories from GitHub, serves git clones over HTTP, stores SHA-scoped Git bundles and legacy code uploads, caches package registry responses, fetches a commit it lacks on demand, and keeps mirrors that were used recently warm.
- [Triggers](https://sparkwing.dev/docs/hooks.md): Pipelines fire from several sources:
- [Install to green](https://sparkwing.dev/docs/install-to-green.md): The demo claim is that a machine with no sparkwing on it reaches a green pipeline run in **under sixty seconds**. `bin/install-to-green.sh` is the measurement behind the claim: it installs the CLI, scaffolds a pipeline, compiles it, runs it, and prints the seconds from install to first green with each phase broken out. `bash bin/install-to-green.sh --help` lists its flags.
- [Local Execution](https://sparkwing.dev/docs/local-execution.md): Sparkwing pipelines run anywhere -- on a Kubernetes cluster, on your laptop, or both. This is a core design advantage: your CI/CD is not a black box in the cloud, it is a portable program you can run yourself.
- [MCP Server](https://sparkwing.dev/docs/mcp.md): Sparkwing will include an MCP (Model Context Protocol) server that exposes pipeline commands to AI agents through a single, context-efficient tool.
- [Local dashboard (native mode)](https://sparkwing.dev/docs/native-mode.md): Running `sparkwing` executes pipelines on your laptop, each job in its own process. Native mode adds one thing on top of that: a way to watch several runs side by side.
- [Observability](https://sparkwing.dev/docs/observability.md): Sparkwing tracks run health, failure reasons, and resource usage so you can debug failures fast and right-size containers.
- [Pipelines](https://sparkwing.dev/docs/pipelines.md): Pipelines define what happens when you run `sparkwing run <name>` (or `sparkwing pipeline run <name>`). See the [SDK guide](sdk.md) for API usage and [Authoring pipelines](authoring-pipelines.md) for the rules enforced by `sparkwing pipeline lint`.
- [Scheduling](https://sparkwing.dev/docs/scheduling.md): How sparkwing decides which runner executes a job. The model is simple: **runners advertise labels, jobs declare the labels they need, and the controller hands each job to a runner whose labels satisfy it.**
- [SDK API reference: `sparkwing/cleanup`](https://sparkwing.dev/docs/sdk-cleanup.md): Package cleanup lets a sparks library guarantee that a resource it starts -- a container, a cluster, a release -- is torn down if the step's node dies before the library's own cleanup runs.
- [SDK API reference: `sparkwing/docker`](https://sparkwing.dev/docs/sdk-docker.md): Package docker is the sparkwing SDK's Docker-shelling helper layer: build, push, login, and deterministic tag computation.
- [SDK API reference: `sparkwing/git`](https://sparkwing.dev/docs/sdk-git.md): Package git is the sparkwing SDK's repo-inspection helper layer: commit SHA, branch, dirty-tree detection, deterministic fileset hash, tag listing, and safe tag push.
- [SDK API reference: `sparkwing/inputs`](https://sparkwing.dev/docs/sdk-inputs.md): Package inputs builds cache keys from files, environment variables, and constants.
- [SDK API reference: `sparkwing/planguard`](https://sparkwing.dev/docs/sdk-planguard.md): Package planguard implements the Plan() purity sentinel.
- [SDK API reference](https://sparkwing.dev/docs/sdk-reference.md): Every exported symbol in the `sparkwing` package (the SDK you import as `sw`), generated from source. Browse the same thing with cross-links on pkg.go.dev: <https://pkg.go.dev/github.com/sparkwing-dev/sparkwing/sparkwing>. For concepts and usage examples, see [sdk.md](sdk.md).
- [SDK API reference: `sparkwing/services`](https://sparkwing.dev/docs/sdk-services.md): Package services is the sparkwing SDK's sidecar-container helper: start sidecars for a function, wait for readiness, and clean up services whose startup succeeded on return, error, panic, or context cancellation.
- [SDK Reference](https://sparkwing.dev/docs/sdk.md): This guide covers pipeline authoring with the `sparkwing` package. The generated [API reference](sdk-reference.md) lists exported signatures; `sdk-<name>.md` pages cover subpackages. Read them offline with `sparkwing docs read --topic sdk-reference` or `--topic sdk-<name>`. See [Pipelines](pipelines.md) for the Plan/Work model and project YAML.
- [Security](https://sparkwing.dev/docs/security.md): How sparkwing protects code, credentials, and infrastructure.
- [Self-hosting Sparkwing](https://sparkwing.dev/docs/self-hosting.md): For the use cases that the former Compose example covered, choose one of these supported paths:
- [sparks-core (Example Spark Library)](https://sparkwing.dev/docs/sparks-core.md): sparks-core is an example of a **spark library** -- a multi-module monorepo of reusable Go modules that provide pipeline helpers, each versioned and consumed independently. It is not part of the sparkwing SDK and is not required to use sparkwing. It demonstrates the pattern of extracting common pipeline logic into shared libraries: your own spark libraries can provide whatever your team needs.
- [Sparks Libraries](https://sparkwing.dev/docs/sparks.md): Reference for the sparks library ecosystem: the `spark.json` manifest, the consumer `sparks:` block in `.sparkwing/sparkwing.yaml`, version resolution, and the `sparkwing pipeline sparks` CLI.
- [Threat model: another person's branch on your machine](https://sparkwing.dev/docs/threat-model.md): Enrolling a workstation as a runner authorizes pipeline code from the repositories that controller schedules to compile and execute on it. This page states what Sparkwing isolates in that case, what it does not, and what an operator does about the rest. [security.md](security.md) covers transport, tokens, and secret storage; [local-execution.md](local-execution.md) covers the local daemon and the laptop boundary.
- [Versioning and the plugin ecosystem](https://sparkwing.dev/docs/versioning.md): How sparkwing, sparks-core, and third-party plugins version themselves, what compatibility you can expect, and the architectural choices behind it. If you're authoring a plugin today, jump to [**What this means for plugin authors**](#what-this-means-for-plugin-authors).
- [Warm PVC Pool](https://sparkwing.dev/docs/warm-pool.md): The warm pool pre-loads Docker build caches onto PVCs so pipeline builds start with warm caches instead of pulling and compiling everything from scratch.

## Other versions

- [v0.55.0](https://sparkwing.dev/v0.55.0/llms.txt)
- [v0.54.0](https://sparkwing.dev/v0.54.0/llms.txt)
- [v0.53.0](https://sparkwing.dev/v0.53.0/llms.txt)
- [v0.52.7](https://sparkwing.dev/v0.52.7/llms.txt)
- [v0.52.6](https://sparkwing.dev/v0.52.6/llms.txt)
- [v0.52.5](https://sparkwing.dev/v0.52.5/llms.txt)
- [v0.52.4](https://sparkwing.dev/v0.52.4/llms.txt)
- [v0.41.0](https://sparkwing.dev/v0.41.0/llms.txt)
- [v0.38.1](https://sparkwing.dev/v0.38.1/llms.txt)
- [v0.38.0](https://sparkwing.dev/v0.38.0/llms.txt)
- [v0.33.0](https://sparkwing.dev/v0.33.0/llms.txt)
- [v0.32.1](https://sparkwing.dev/v0.32.1/llms.txt)
- [v0.32.0](https://sparkwing.dev/v0.32.0/llms.txt)
- [v0.31.0](https://sparkwing.dev/v0.31.0/llms.txt)
- [v0.30.0](https://sparkwing.dev/v0.30.0/llms.txt)
- [v0.29.0](https://sparkwing.dev/v0.29.0/llms.txt)
- [v0.28.0](https://sparkwing.dev/v0.28.0/llms.txt)
- [v0.27.0](https://sparkwing.dev/v0.27.0/llms.txt)
- [v0.26.0](https://sparkwing.dev/v0.26.0/llms.txt)
- [v0.25.0](https://sparkwing.dev/v0.25.0/llms.txt)
- [v0.24.0](https://sparkwing.dev/v0.24.0/llms.txt)
- [v0.23.1](https://sparkwing.dev/v0.23.1/llms.txt)
- [v0.22.0](https://sparkwing.dev/v0.22.0/llms.txt)
- [v0.20.0](https://sparkwing.dev/v0.20.0/llms.txt)
- [v0.19.0](https://sparkwing.dev/v0.19.0/llms.txt)
- [v0.18.0](https://sparkwing.dev/v0.18.0/llms.txt)
- [v0.17.0](https://sparkwing.dev/v0.17.0/llms.txt)
- [v0.16.3](https://sparkwing.dev/v0.16.3/llms.txt)
- [v0.16.2](https://sparkwing.dev/v0.16.2/llms.txt)
- [v0.15.2](https://sparkwing.dev/v0.15.2/llms.txt)
- [v0.14.1](https://sparkwing.dev/v0.14.1/llms.txt)
- [v0.13.0](https://sparkwing.dev/v0.13.0/llms.txt)
- [v0.12.0](https://sparkwing.dev/v0.12.0/llms.txt)
- [v0.11.2](https://sparkwing.dev/v0.11.2/llms.txt)
- [v0.11.0](https://sparkwing.dev/v0.11.0/llms.txt)
- [v0.10.0](https://sparkwing.dev/v0.10.0/llms.txt)
- [v0.9.1](https://sparkwing.dev/v0.9.1/llms.txt)
- [v0.8.0](https://sparkwing.dev/v0.8.0/llms.txt)
- [v0.7.1](https://sparkwing.dev/v0.7.1/llms.txt)
- [v0.6.0](https://sparkwing.dev/v0.6.0/llms.txt)
- [v0.5.0](https://sparkwing.dev/v0.5.0/llms.txt)
- [v0.4.0](https://sparkwing.dev/v0.4.0/llms.txt)
- [v0.3.0](https://sparkwing.dev/v0.3.0/llms.txt)
- [v0.56.0 (this file, versioned alias)](https://sparkwing.dev/v0.56.0/llms.txt)

## Migration guides

Per-version guides for releases with breaking changes. Adopters jumping multiple versions follow them in order.

- [Migration guides index](https://sparkwing.dev/migrations.txt)
- [Full migration corpus (one file)](https://sparkwing.dev/migrations-full.txt)

## Resources

- [Full docs corpus for v0.56.0 (one file)](https://sparkwing.dev/llms-full.txt)
- [Install the CLI](https://sparkwing.dev/install.sh)