StageFreight

README

StageFreight

Hello World's a Stage

A declarative CI/CD automation CLI that detects, builds, scans, and releases container images across forges and registries — from a single manifest. StageFreight is open-source, self-building, and replaces fragile shell-script CI pipelines with a single Go binary driven by one .stagefreight.yml file.

Features:

Detect → Plan → Build	Finds Dockerfiles, resolves tags from git, builds multi-platform images via docker buildx
Multi-Registry Push	Docker Hub, GHCR, GitLab, Quay, Harbor, JFrog, Gitea — with branch/tag filtering via regex (! negation)
Security Scanning	Trivy + Grype vulnerability scan, Syft SBOM generation, configurable detail levels per branch or tag
Cross-Forge Releases	Create releases on GitLab, GitHub, or Gitea with auto-generated notes, badges, and cross-platform sync
Cache-Aware Linting	9 lint modules run in parallel, delta-only on changed files, with JUnit reporting for CI
Retention Policies	Restic-style tag retention (keep_last, daily, weekly, monthly, yearly) across all registry providers
Self-Building	StageFreight builds itself — this image is produced by stagefreight docker build

Documentation:

CLI Reference	Full Command Reference
Config Reference	Full Config Schema
Manifest Examples	24 Example Configs · Quick Examples
Roadmap	Full Vision
GitLab CI Component	Component Reference · Template

---

Quick Start

# .stagefreight.yml
version: 1

builds:
  - id: myapp
    kind: docker
    platforms: [linux/amd64]

targets:
  - id: dockerhub
    kind: registry
    build: myapp
    url: docker.io
    path: yourorg/yourapp
    tags: ["{version}", "latest"]
    when: { events: [tag] }
    credentials: DOCKER

# .gitlab-ci.yml
build-image:
  image: docker.io/prplanit/stagefreight:latest-dev
  services:
    - docker.io/library/docker:27-dind
  script:
    - stagefreight docker build
  rules:
    - if: '$CI_COMMIT_TAG'

# or run locally
docker run --rm -v "$(pwd)":/src -w /src \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker.io/prplanit/stagefreight:latest-dev \
  sh -c 'git config --global --add safe.directory /src && stagefreight docker build --local'

---

CLI Commands

stagefreight docker build       # detect → plan → lint → build → push → retention
stagefreight docker readme      # sync README to container registries
stagefreight lint                # run lint modules on the working tree
stagefreight security scan      # trivy + grype scan + SBOM generation
stagefreight release create     # create forge release with notes + sync
stagefreight release notes      # generate release notes from git log
stagefreight release badge      # generate/commit release status badge SVG
stagefreight release prune      # prune old releases via retention policy
stagefreight badge generate     # generate SVG badges from config
stagefreight narrator run       # compose narrator items into target files
stagefreight narrator compose   # ad-hoc CLI-driven composition
stagefreight docs generate      # generate CLI + config reference docs
stagefreight component docs     # generate component input documentation
stagefreight dependency update  # update dependencies with freshness analysis
stagefreight migrate            # migrate config to latest schema version
stagefreight version            # print version info

See CLI Reference for full flag documentation.

---

Image Contents

Base Images

Runtime Packages

Looking for a minimal image?

Image	Purpose
prplanit/stagefreight:0.1.1	Last pre-CLI release — vanilla DevOps toolchain (bash, docker-cli, buildx, python3, yq, jq, etc.)
prplanit/ansible-oci	Ansible-native image — Python 3.13 + Alpine 3.22, ansible-core, ansible-lint, sops, rage, pywinrm, kubernetes.core, community.docker, community.sops

Starting from 0.2.0, prplanit/stagefreight includes the Go CLI binary and is purpose-built for stagefreight docker build workflows.

---

Contributing

• Fork the repository
• Submit Pull Requests / Merge Requests
• Open issues with ideas, bugs, or feature requests

Disclaimer

The Software provided hereunder is licensed "as-is," without warranties of any kind. The developer makes no promises about functionality, performance, or availability. Not responsible if StageFreight replaces your entire CI pipeline and you find yourself with free time you didn't expect, your retention policies work so well your registry bill drops and finance gets confused, or your release notes become more detailed than the actual features they describe.

Any resemblance to working software is entirely intentional but not guaranteed. The developer claims no credit for anything that actually goes right — that's all you and the unstoppable force of the Open Source community.

License

Distributed under the AGPL-3.0-only License. See LICENSING.md for commercial licensing.