Skip to content

Docker.md

Latest commit

 

History

History
268 lines (204 loc) · 7.37 KB

Docker.md

File metadata and controls

268 lines (204 loc) · 7.37 KB
Raw

StageFreight — Docker Build Configuration

How StageFreight builds, pushes, and manages container images using the builds: and targets: sections of .stagefreight.yml.

Reference docs: Config Reference — builds · Config Reference — targets · CLI Reference — docker

Builds

A build defines how to produce a container image. Each build has a unique ID that targets reference.

builds:
  - id: myapp
    kind: docker
    platforms: [linux/amd64, linux/arm64]
    dockerfile: "Dockerfile"
    context: "."
    build_args:
      GO_VERSION: "1.25"

Currently the only supported kind is docker. Future kinds may include helm or binary.

Build Mode: Crucible

Crucible mode performs a self-proving rebuild — the image is built twice and the layers are compared to verify reproducibility.

builds:
  - id: myapp
    kind: docker
    build_mode: crucible

Targets

Targets define where build artifacts go. Each target has a kind that determines its behavior.

Registry Target

Pushes image tags to a container registry.

targets:
  - id: dockerhub-stable
    kind: registry
    build: myapp              # references builds[].id
    url: docker.io
    provider: docker          # auto-detected from URL if omitted
    path: myorg/myapp
    tags:
      - "{version}"
      - "{major}.{minor}"
      - "latest"
    when:
      git_tags: [stable]      # policy name from policies.git_tags
      events: [tag]
    credentials: DOCKER       # → DOCKER_TOKEN or DOCKER_USER + DOCKER_PASS
    retention:
      keep_last: 10
      keep_monthly: 6

Docker README Target

Syncs your README to container registries 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"

Provider Values

Provider Registry
docker Docker Hub
ghcr GitHub Container Registry
gitlab GitLab Container Registry
quay Quay.io
harbor Harbor
jfrog JFrog Artifactory
gitea Gitea Container Registry
generic Any OCI registry

Registry Credentials

The credentials field on a registry target sets an environment variable prefix. StageFreight resolves the actual secret from your CI/CD variables at runtime — nothing sensitive lives in .stagefreight.yml.

Resolution order

For a given prefix (e.g. HARBOR), StageFreight checks these suffixes in order, stopping at the first non-empty value:

Suffix Example Notes
_TOKEN HARBOR_TOKEN Preferred. Scoped, revocable API token.
_PASS HARBOR_PASS Accepted. Warning emitted recommending _TOKEN.
_PASSWORD HARBOR_PASSWORD Accepted. Warning emitted recommending _TOKEN.

Username is always read from {PREFIX}_USER (e.g. HARBOR_USER).

At the registry protocol level, all three are identical — they become the --password-stdin value passed to docker login. The distinction is entirely on the issuing side:

  • Password — authenticates the account directly. If it leaks, an attacker has account-level access. Rotating it affects every system using that account.
  • Token — a credential issued separately from the account password. Tokens can be scoped to specific registries, projects, or actions (e.g. push-only, no delete, no admin). They can be revoked individually without touching the account or other tokens. Access logs attribute activity to the token, not the account, giving a cleaner audit trail.

Recommendation: create a robot account or API token in your registry with the minimum permissions needed (typically: push to the specific project), store it as {PREFIX}_TOKEN in your CI/CD variables, and never store your account password in CI at all.

Silencing the warning

If you set {PREFIX}_PASS or {PREFIX}_PASSWORD but the warning is noise for your setup (e.g. the value is already a token and you just named the variable _PASS), you can silence it by renaming the CI/CD variable to use the _TOKEN suffix. StageFreight has no way to distinguish a password from a token by value — the warning is purely based on which suffix was matched.

Example — Harbor with a robot account token

# .stagefreight.yml
targets:
  - id: harbor-dev
    kind: registry
    build: myapp
    url: cr.example.com
    provider: harbor
    path: myorg/myapp
    tags: ["dev-{sha:8}", "latest-dev"]
    when: { branches: [main], events: [push] }
    credentials: HARBOR
# GitLab CI/CD variables
HARBOR_USER   =  robot$myorg+stagefreight-push
HARBOR_TOKEN  =  <robot account secret>

Build Cache

Controls cache invalidation rules for incremental builds.

builds:
  - id: myapp
    kind: docker
    cache:
      auto_detect: true       # detect lockfile changes (default: true)
      watch:
        - paths: ["go.sum"]
          invalidates: ["COPY go.* ./", "RUN go mod download"]

Build Strategy Selection

StageFreight selects a build strategy automatically:

Condition Strategy Behavior
--local flag local --load into daemon, no push
Single platform + registries load + push --load then docker push each tag
Multi-platform + registries multi-platform push --push directly (can't --load multi-arch)
No registries local --load, default tag stagefreight:dev

Retention Policy

Used by registry and release targets. Policies are additive (restic-style) — a tag survives if any rule wants to keep it.

# Shorthand
retention: 10                    # keep last 10

# Full policy
retention:
  keep_last: 3
  keep_daily: 7
  keep_weekly: 4
  keep_monthly: 6
  keep_yearly: 2
  protect: ["latest"]            # never deleted

Pattern Syntax

Used by when.branches, when.git_tags, and all conditional fields.

"^main$"              # regex match (default)
"!^feature/.*"        # negated regex (! prefix)
"main"                # literal match
"!develop"            # negated literal

Empty list = no filter (always matches). Multiple patterns: evaluated in order, first match wins.

CLI Commands

See CLI Reference for full flag documentation.

stagefreight docker build [flags]    # detect → plan → lint → build → push → retention
stagefreight docker readme [flags]   # sync README to container registries

Pipeline Phases

During stagefreight docker build, these phases run in order:

  1. Lint — pre-build lint gate (skippable with --skip-lint)
  2. Detect — find Dockerfiles, detect language, resolve context
  3. Plan — resolve platforms, tags, registries, build strategy
  4. Build — execute docker buildx with layer-parsed output
  5. Push — push tags to remote registries
  6. Retention — prune old tags per retention policies

Badges, README sync, and narrator run as separate CI steps:

stagefreight badge generate → stagefreight docs generate → stagefreight narrator run → stagefreight docker readme