Config reference
Config reference
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. A sparkwing.yaml larger than 1 MiB is refused before it is parsed. See storage backends for profiles and spark libraries for library configuration.
Pipeline entry (a pipelines: list item)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Name is the invocable name (sparkwing run <name>), independent of the SDK registration key. It must match ^[A-Za-z0-9][A-Za-z0-9._-]*$. |
entrypoint | string | yes | Entrypoint is the key the SDK registered this entry's pipeline under, such as sparkwing.Register("Deploy", ...). Required. |
source | string | no | Source selects the Git ref to compile; jobs still execute in the submitted checkout. |
description | string | no | Description is the one-line summary surfaced by pipeline list. |
on | Triggers | no | On declares the triggers that auto-fire this pipeline. Absent means manual-only (a command invoked by name). |
hidden | bool | no | Hidden omits the entry from default pipeline list output; it stays invocable by exact name and shows under list --all. |
guards | Guards | no | Guards gate dispatch on where the run is dispatched, args, and git branch. Reject fires before any step runs when any token matches; Require fires when not every token matches. Token vocabulary: where:local, where:controller, arg:<flag>=<value>, git:branch=<name>, git:branch=default. A literal branch matches the checked-out head. The default token matches the repository's default branch: a GitHub App trigger records it, and any other run reads origin's HEAD from its checkout; a run that cannot resolve it is refused. arg: tokens read the merged argument set the run executes with, so a value supplied by defaults.args, this entry's own args: block or a flag's SDK default is guarded exactly like one typed on the command line. See pkg/pipelines/guards.go. |
args | map[string]string | no | Args supplies per-arg default values. Higher priority than a field's default tag; lower than an explicit operator CLI flag. Keyed by the field's flag tag on pipeline Inputs or a job's WithArgs[T]. |
profile | string | no | Profile pins the pipeline to the controller profile it names: sparkwing run refuses it, and sparkwing pipeline trigger accepts only --profile with this name. Empty leaves the pipeline unpinned. |
requires | []string | no | Requires are runner-label requirements all jobs in this pipeline must satisfy in addition to their own Job.Requires(). Wholesale replaces defaults.requires when non-empty. The reserved label "local" keeps fleet helpers from claiming the node. |
guards
| Field | Type | Required | Description |
|---|---|---|---|
require | []string | no | |
reject | []string | no |
Triggers (on:)
| Field | Type | Required | Description |
|---|---|---|---|
push | PushTrigger | no | Push fires on a git push the controller receives via webhook. |
pull_request | PullRequestTrigger | no | PullRequest fires on a GitHub pull_request event the controller receives via webhook. The run checks out the PR head; base ref and PR number reach the pipeline on RunContext.Trigger.PullRequest. |
schedule | ScheduleTriggers | no | Schedule fires the pipeline on one or more cron cadences. It accepts one mapping or a list of mappings; every entry declares where it fires, so a bare cron string is refused. |
webhook | WebhookTrigger | no | Webhook exposes a custom HTTP path that fires the pipeline. |
pre_commit | PreHookTrigger | no | PreHook fires from the installed git pre-commit hook. |
pre_push | PostHookTrigger | no | PostHook fires from the installed git pre-push hook. |
post_commit | PostCommitHookTrigger | no | PostCommitHook fires from the installed git post-commit hook, after the commit is recorded. It never blocks or aborts the commit. |
on.push
| Field | Type | Required | Description |
|---|---|---|---|
branches | []string | no | Branches filters repository automation with Go path.Match globs. |
paths | []string | no | Paths requires complete changed-file evidence; repository automation refuses declarations with this filter. |
on.pull_request
| Field | Type | Required | Description |
|---|---|---|---|
actions | []string | no | Actions defaults to opened, synchronize, and reopened. Repository automation also supports closed and ready_for_review. |
branches | []string | no | Branches filters the pull request's base branch with Go path.Match globs. |
on.schedule
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | Name distinguishes several cadences on one pipeline and appears in sparkwing schedules list as //. Required once a pipeline declares more than one entry; a lone entry is named "default". It matches ^[a-z0-9][a-z0-9-]*$ and is at most 40 characters. |
cron | string | yes | Cron is a five-field cron expression (minute hour day-of-month month day-of-week) with the usual lists, ranges, steps, month and day names, and the @hourly/@daily/@weekly/@monthly/@yearly aliases. |
where | string | yes | Where says which side fires this entry: "local" fires from a host that armed it with sparkwing schedules install, "controller" from a controller it was installed on. One side per entry, and there is no default, so nothing fires somewhere you did not say it should. Declare one entry per side to fire from both. |
tz | string | no | TZ is the IANA zone the expression is read in, such as America/Denver. Default UTC. The word "local" means the zone of the host that runs the schedule. |
overlap | string | no | Overlap decides what happens when the cadence comes due while the previous scheduled run is still running: "skip" (default) records the fire as skipped, "queue" launches it anyway and lets admission order it. |
catch_up | string | no | CatchUp is how long after its due minute a fire may still happen when the host was asleep or the timer was late, as a Go duration such as 1h or 30m. Default 1h; values under 2m are rejected, and a value over 24h is lowered to 24h when the schedule is evaluated. A due minute older than the window is recorded as missed. |
args | map[string]string | no | Args supplies argument values for this cadence's runs, keyed by CLI flag name exactly like args: on the pipeline. They sit above pipeline.args and below a host's own override for the schedule, so guards' arg: tokens read them and the fire records what it ran with. |
on.webhook
| Field | Type | Required | Description |
|---|---|---|---|
path | string | yes | Path is the HTTP path the controller exposes to fire the pipeline (e.g. /review). |