Targets

targets: declares what StageFreight does with a build — push image tags, sync a registry README, publish a GitLab component, cut a forge release, publish an archive or package, or deploy a static site. Each entry is a discriminated union keyed by kind: the kind decides which other keys are valid.

Every target shares an id (unique) and a when: routing block (all non-empty conditions must match — AND logic; see Patterns & conditions).

Registry — push image tags

Pushes a build's image to a container registry under one or more tags:.

targets:
  - id: dockerhub-stable
    kind: registry
    build: myapp                 # references builds[].id
    url: docker.io
    provider: docker             # auto-detected from the URL if omitted
    path: myorg/myapp
    tags:
      - "{version}"
      - "{major}.{minor}"
      - "latest"
    when:
      git_tags: [stable]         # a named matcher from matchers:
      events: [tag]
    credentials: DOCKER          # env-var prefix — see Concepts → Credentials
    retention:
      keep_last: 10
      keep_monthly: 6

provider is auto-detected from url when omitted; the generated reference below lists the recognized providers (Docker Hub, GHCR, GitLab, Quay, Harbor, JFrog, Gitea, generic OCI). credentials, tags template expansion, and retention are cross-cutting — see Concepts.

Docker README — sync registry descriptions

Syncs a README to container-registry description fields, with badge injection and link rewriting.

targets:
  - id: dockerhub-readme
    kind: docker-readme
    url: docker.io
    path: myorg/myapp
    credentials: DOCKER
    file: "README.md"
    description: "Short description for Docker Hub"
    link_base: "https://github.com/myorg/myrepo/blob/main"

Release — cut forge releases

Creates a release on the detected forge, with rolling git-tag aliases that track it.

targets:
  - id: primary-release
    kind: release
    aliases: ["{version}", "{major}.{minor}", "latest"]
    retention:
      keep_last: 10
      keep_monthly: 6
    when: { git_tags: [stable], events: [tag] }

The aliases are rolling git tags resolved with the same template variables as everything else — {version} → 1.2.3, {major}.{minor} → 1.2, latest → always the newest.

Mirroring to a remote forge

Provide the remote forge's coordinates and a sync_* toggle to mirror releases (release notes, tags, and scan assets) to a second forge — for example, cutting on GitLab and mirroring to GitHub. Supported providers: github, gitlab, gitea.

targets:
  - id: github-sync
    kind: release
    provider: github
    url: "https://github.com"
    project_id: "myorg/myapp"
    credentials: GITHUB_SYNC     # → GITHUB_SYNC_TOKEN
    aliases: ["{version}"]
    when: { git_tags: [stable], events: [tag] }
    sync_release: true           # mirror release notes and tags
    sync_assets: true            # upload scan artifacts

Retention on a mirror target prunes the mirror's releases with the same policy semantics as the primary — no surprising deletions, and pre-release status is carried across even where the remote forge has no native pre-release field.

CLI

Release authoring (release create, release notes, release prune, release badge) and its flags live in the CLI Reference. In CI these run as part of the publish phase; you rarely invoke them by hand.

Other target kinds

component (GitLab CI/CD component publish), archive/package distribution (kind: generic-package), and pages (static-site deploy, e.g. these docs to Cloudflare Pages) are declared the same way — a kind, a build: or source, and a when:. Their full field sets are in the generated reference below.

Reference

The blocks below are generated from the config source — for each kind, exactly the fields it accepts, with each field's meaning, allowed values, and whether it's required.

targets

Distribution targets and side-effects. Each target has a kind that determines its behavior: push images, sync READMEs, publish components, or create releases.

kind: registry

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: registry   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    registry: <string>   # Registry references a registries[].id for registry/docker-readme targets. When set…
    build: <string>   # Build references a BuildConfig.ID. Required for kind: registry.
    tags: [<string>]   # Tags are tag templates resolved against version info (kind: registry). e.g., ["{version}"…
    signing_profile: <string>   # SigningProfile references a signing_profiles[].id — the trust profile this target signs under.…
    native_scan: false   # NativeScan enables post-push vulnerability scanning via the registry's own built-in scanner.…
    retention:   # Retention controls cleanup of old tags/releases. Structured only in v2 (no scalar shorthand).
      keep_last: <int>   # keep the N most recent tags · required
      keep_daily: <int>   # keep one per day for the last N days · required
      keep_weekly: <int>   # keep one per week for the last N weeks · required
      keep_monthly: <int>   # keep one per month for the last N months · required
      keep_yearly: <int>   # keep one per year for the last N years · required
      protect: [<string>]   # tag patterns that are never deleted (v2) · required
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

kind: docker-readme

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: docker-readme   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    registry: <string>   # Registry references a registries[].id for registry/docker-readme targets. When set…
    file: <string>   # File is the path to the README file (kind: docker-readme).
    link_base: <string>   # LinkBase is the base URL for relative link rewriting (kind: docker-readme).
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

kind: gitlab-component

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: gitlab-component   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    spec_files: [<string>]   # SpecFiles lists component spec file paths (kind: gitlab-component).
    catalog: false   # Catalog enables GitLab Catalog registration (kind: gitlab-component).
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

kind: release

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: release   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    aliases: [<string>]   # Aliases are rolling git tag aliases (kind: release). e.g., ["{version}", "{major}.{minor}"…
    tag: <string>   # Tag is the immutable identity pattern for a release channel (kind: release). Distinct from Aliases…
    archives: <string>   # Archives references a binary-archive target ID (kind: release and generic-package).
    prerelease: false   # Prerelease marks the forge release as a pre-release (kind: release). Honored natively by…
    mirror: <string>   # Mirror references a sources.mirrors[].id for release sync. Forge identity (provider, url…
    sync_release: false   # SyncRelease syncs release notes + tags to a remote forge (kind: release, remote only).
    sync_assets: false   # SyncAssets syncs scan artifacts to a remote forge (kind: release, remote only).
    signing_profile: <string>   # SigningProfile references a signing_profiles[].id — the trust profile this target signs under.…
    retention:   # Retention controls cleanup of old tags/releases. Structured only in v2 (no scalar shorthand).
      keep_last: <int>   # keep the N most recent tags · required
      keep_daily: <int>   # keep one per day for the last N days · required
      keep_weekly: <int>   # keep one per week for the last N weeks · required
      keep_monthly: <int>   # keep one per month for the last N months · required
      keep_yearly: <int>   # keep one per year for the last N years · required
      protect: [<string>]   # tag patterns that are never deleted (v2) · required
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

kind: binary-archive

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: binary-archive   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    build: <string>   # Build references a BuildConfig.ID. Required for kind: registry.
    name: <string>   # Name is the archive filename template (kind: binary-archive). Supports: {id}, {version}, {os}…
    format: <string>   # Format is the archive format: "tar.gz", "zip", "auto", or "binary" (kind: binary-archive). "auto"… · one of: auto, binary, tar.gz, zip
    binary_name: <string>   # BinaryName overrides the binary name inside the archive (kind: binary-archive). Auto-detected from…
    include: [<string>]   # Include lists extra files to bundle into the archive (kind: binary-archive). e.g., ["README.md"…
    checksums: false   # Checksums generates a SHA256SUMS file alongside archives (kind: binary-archive).
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

kind: generic-package

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: generic-package   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    repo: <string>   # Repo references a repos[].id (kind: generic-package). The forge identity (provider, url, project…
    package: <string>   # Package is the generic package name (kind: generic-package). Defaults to the repo project's…
    version: <string>   # Version is the immutable package version pattern (kind: generic-package). Resolved against version…
    archives: <string>   # Archives references a binary-archive target ID (kind: release and generic-package).
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

kind: pages

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: pages   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    provider: <string>   # Provider is the vendor type for auth and API behavior. Registry: docker, ghcr, gitlab, jfrog… · one of: cloudflare, github
    build: <string>   # Build references a BuildConfig.ID. Required for kind: registry.
    dir: <string>   # Dir publishes a repo directory directly instead of a build's output tree (kind: pages). Exactly one…
    domain: [<string>]   # Domain is the custom domain(s) (kind: pages). Accepts a bare scalar or a list:
    project: <string>   # Project is the Cloudflare Pages project name (provider: cloudflare). Default: the target id.…
    base_path: <string>   # BasePath is the URL path the site is served under (kind: pages). Inferred per provider (Cloudflare…
    exclude: [<string>]   # Exclude drops matching paths from the publish workspace before deploy (kind: pages). Globs, applied…
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

Target IDs must be unique across all targets. The when block controls routing: all non-empty fields must match (AND logic).

---