ReleaseFlow Documentation

Complete guide to using ReleaseFlow (rflow) for enterprise-grade release orchestration and supply chain security.

What is ReleaseFlow?

ReleaseFlow (rflow) is a manifest-driven CLI tool designed to standardize, secure, and orchestrate software releases across complex environments. It decouples release logic from CI/CD pipelines, providing a single source of truth for every artifact, its provenance, and its security posture.

Key Features

Immutable Release Manifests: Every release produces a versioned manifest documenting source, artifacts, and security posture
Security First: Built-in SBOM generation, vulnerability scanning, and image signing
Policy Gates: Automated verification ensuring artifacts meet compliance requirements
Environment Promotion: Safe, auditable promotion of releases across dev → staging → prod
CI/CD Agnostic: Works with any CI/CD system or can be run locally

Installation

ReleaseFlow can be installed using several methods depending on your platform and preferences.

Option 1: Homebrew (Recommended for macOS)

bash

brew install releaseflow/tap/rflow

Option 2: Automatic Installer (Linux/macOS)

This script detects your OS, downloads the release, and configures your PATH automatically.

bash

curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash

Option 3: Manual Installation

For manual installation, download the appropriate binary for your platform from the releases page and add it to your PATH.

Note: Ensure the binary is executable: chmod +x rflow

Prerequisites

Before using ReleaseFlow, ensure you have the following tools installed and available in your PATH:

git - Version control system
docker - Container runtime (or compatible runtime like Podman)
trivy - Vulnerability scanner (for rflow scan images)
syft - SBOM generator (for rflow sbom generate)
cosign - Image signing tool (for rflow sign images)

Verify Your Environment

You can verify your environment setup at any time by running:

bash

rflow doctor

This command checks for all required dependencies and reports any missing tools or configuration issues.

Quick Start

Get up and running with ReleaseFlow in minutes.

Step 1: Initialize Your Project

Launch the interactive wizard to bootstrap your configuration:

bash

# Standard initialization
rflow init

# Initialize with a custom template
rflow init --template /path/to/template.yaml

# Initialize a new project by cloning a remote repository first
rflow init --repo git@github.com:org/repo.git --template my-template.yaml

Step 2: Review Your Configuration

The initialization wizard creates a release.yaml file in your project root. Review and customize it as needed.

Step 3: Generate Your First Manifest

bash

rflow manifest generate

Step 4: Build and Secure Your Release

bash

# Build images
rflow build --manifest manifests/releases/release-v1.0.0.yaml

# Generate SBOMs
rflow sbom generate --manifest manifests/releases/release-v1.0.0.yaml

# Scan for vulnerabilities
rflow scan images --manifest manifests/releases/release-v1.0.0.yaml

# Sign images
rflow sign images --manifest manifests/releases/release-v1.0.0.yaml --key azurekms://...

Step 5: Verify and Promote

bash

# Verify the release meets all policy gates
rflow verify --manifest manifests/releases/release-v1.0.0.yaml --key pubkey.pem

# Promote to staging environment
rflow promote --version 1.0.0 --env staging

Configuration: release.yaml

ReleaseFlow is configured via a release.yaml file in your project root. This file defines your project structure, versioning strategy, registries, services, and security policies.

Complete Schema

release.yaml (Complete Schema)

yaml

schemaVersion: v1

project:
  name: my-app
  owner: my-org
  repo:
    provider: ado | github | gitlab | generic
    url: https://github.com/my-org/my-app
    defaultBranch: main
  releaseFlowRepo:
    provider: ado | github | gitlab | generic
    url: https://github.com/my-org/releaseflow
    branch: main

versioning:
  model: semver
  tagPrefix: v
  sourceOfTruth: release-flow | app
  allowManualLevelOnMaster: false
  releaseLevels:
    master: patch
    develop: minor
    release: minor
    hotfix: patch

registry:
  type: acr | ecr | ghcr | generic
  host: myregistry.azurecr.io
  auth:
    method: docker-login | oidc | service-connection
    reference: service-connection-name

services:
  - name: api
    type: container | directory | file
    image: my-api
    path: .
    dockerfile: Dockerfile
    build:
      args:
        KEY: value
      labels:
        KEY: value
    publish:
      enabled: true
      tags:
        - "{{.Version}}"
        - latest
    security:
      sbom:
        enabled: true
        format: spdx-json | cyclonedx-json
        outputPath: security/sbom/{{.Service}}-{{.Version}}.spdx.json
      scan:
        enabled: true
        tool: trivy
        severityFail:
          - CRITICAL
          - HIGH
        ignoreFile: .trivyignore
        outputPath: security/scans/{{.Service}}-{{.Version}}.trivy.json
      aiArtifacts:
        enabled: true
        modelId: gemini-2.5-flash
        provider: google
        generatedPaths:
          - src/components/ai-generated/*
      redTeam:
        enabled: true
        framework: pyrit
        timeoutMinutes: 30

manifest:
  enabled: true
  latestPath: manifests/release-manifest.yaml
  versionedPath: manifests/releases/release-{{.Version}}.yaml
  include:
    git: true
    appCommit: true
    security: true
    signatures: true

signing:
  git:
    enabled: true
    method: gpg
    keyIdEnv: GPG_KEY_ID
    passphraseEnv: GPG_PASSPHRASE
    privateKeyEnv: GPG_PRIVATE_KEY
  images:
    enabled: true
    method: cosign
    keyProvider: azurekms | file | keyless
    keyRef: azurekms://vault.vault.azure.net/key
    tlogUpload: false
    annotations:
      KEY: value

secrets:
  provider: azure-keyvault
  vaultName: https://vault.vault.azure.net/

notes:
  internal:
    sourceDir: .release/notes/internal
    outputPath: release-notes/internal/{{.Version}}.md
  external:
    sourceDir: .release/notes/external
    outputPath: release-notes/external/{{.Version}}.md
  changelog:
    mode: from-commits | from-files | none
    conventionalCommits: false

policy:
  enabled: true
  gates:
    requireSignedGitTag: true
    requireSignedImages: true
    requireSbom: true
    requireScan: true
    enforceAgentPolicies: true
    failOnSeverities:
      - CRITICAL
  exceptions:
    allowedCves:
      - CVE-2025-12345
    allowUnfixed: false
  agentGuardrails:
    maxIterations: 10
    allowedTools:
      - read_file
      - bash
    anomalyScoreThreshold: 0.8

promotion:
  enabled: true
  environments:
    - name: dev
      requiresApproval: false
      approvers: []
    - name: staging
      requiresApproval: true
      approvers:
        - user@example.com
    - name: prod
      requiresApproval: true
      approvers:
        - admin@example.com

Project Configuration

The project section defines metadata about your project and repositories.

yaml

project:
  name: string                 # e.g. "my-app"
  owner: string                # org/team name
  repo:
    provider: string           # "ado" | "github" | "gitlab" | "generic"
    url: string                # repo URL (human readable)
    defaultBranch: string      # e.g. "main" or "master"
  releaseFlowRepo:
    url: string                # e.g. "https://github.com/my-org/releaseflow"
    branch: string             # e.g. "main"

Example

yaml

project:
  name: my-api
  owner: my-org
  repo:
    provider: github
    url: https://github.com/my-org/my-api
    defaultBranch: main
  releaseFlowRepo:
    url: https://github.com/my-org/releaseflow
    branch: main

Versioning Strategy

ReleaseFlow supports Semantic Versioning (SemVer) for version management.

yaml

versioning:
  model: semver
  initialVersion: 0.1.0        # Starting version for new projects

Version Bumping

You can bump versions manually or automatically during manifest generation:

bash

# Manual version bump
rflow version bump patch
rflow version bump minor
rflow version bump major

# Automatic bump during manifest generation
rflow manifest generate --bump patch

Container Registries

Configure where your container images will be stored and published.

yaml

registry:
  type: acr | ecr | ghcr | generic
  host: myregistry.azurecr.io
  auth:
    method: docker-login | oidc | service-connection
    reference: service-connection-name

Azure Container Registry Example

yaml

registry:
  type: acr
  host: myregistry.azurecr.io
  auth:
    method: service-connection
    reference: my-release-flow-connection

Services Definition

Define the containerized services or other artifacts that make up your application.

yaml

services:
  - name: api
    type: container
    image: my-api
    path: .
    dockerfile: Dockerfile
    build:
      args:
        BUILD_VERSION: "{{.Version}}"
        NODE_ENV: production
      labels:
        org.opencontainers.image.version: "{{.Version}}"
    publish:
      enabled: true
      tags:
        - "{{.Version}}"
        - latest
    security:
      sbom:
        enabled: true
        format: spdx-json
        outputPath: security/sbom/{{.Service}}-{{.Version}}.spdx.json
      scan:
        enabled: true
        tool: trivy
        severityFail:
          - CRITICAL
          - HIGH
        outputPath: security/scans/{{.Service}}-{{.Version}}.trivy.json

Multi-Service Example

yaml

services:
  - name: frontend
    type: container
    image: myapp-frontend
    path: ./frontend
    dockerfile: Dockerfile
    publish:
      enabled: true
      tags: ["{{.Version}}", "latest"]
  
  - name: backend
    type: container
    image: myapp-backend
    path: ./backend
    dockerfile: Dockerfile
    build:
      args:
        DATABASE_URL: ${DATABASE_URL}
    publish:
      enabled: true
      tags: ["{{.Version}}"]
  
  - name: terraform-module
    type: directory
    path: infrastructure/modules/vpc
    security:
      scan:
        enabled: true
        tool: trivy

Security Policies

Define security policies that must be satisfied before a release can be promoted.

yaml

policy:
  enabled: true
  gates:
    requireSignedGitTag: true
    requireSignedImages: true
    requireSbom: true
    requireScan: true
    failOnSeverities:
      - CRITICAL
      - HIGH
  exceptions:
    allowedCves:
      - CVE-2025-12345
    allowUnfixed: false

Commands Reference

rflow init

Interactive wizard to bootstrap your ReleaseFlow configuration.

bash

rflow init [flags]

Flags:
  --template string    Path to a custom template file
  --repo string        Git repository URL to clone first
  --config string      Output config file path (default: release.yaml)

Example

bash

# Standard initialization
rflow init

# With custom template
rflow init --template ./templates/microservices.yaml

rflow manifest generate

Generates the immutable release manifest. This establishes the "plan" for the release.

bash

rflow manifest generate [flags]

Flags:
  --config string            Path to release.yaml (default: release.yaml)
  --bump string              Version bump level: patch|minor|major (optional)
  --version string           Explicit version (optional; otherwise read from .version)
  --app-dir string           Path to app repo checkout (optional but recommended)
  --app-sha string           Explicit App Commit SHA (overrides detection from app-dir)
  --write-version            When bumping, write updated version back to .version (default: true)
  --fail-on-severity strings List of severities to fail on (comma separated). Default CRITICAL.
  --record-cosign-verify     Record cosign verification evidence from security/cosign/*.verify.json (default: true)
  --ai-assist                Use AI to evaluate manifest security and propose policy improvements
  --ai-provider string       AI Provider for assist (gemini|claude|grok|ollama)

Examples

bash

# Generate manifest with automatic patch bump
rflow manifest generate --bump patch

# Generate manifest with explicit version
rflow manifest generate --version 2.0.0

# Generate manifest from different app directory
rflow manifest generate --app-dir ../my-app

# Generate manifest with explicit commit SHA
rflow manifest generate --app-dir ../my-app --app-sha abc123def

# Generate manifest with an AI-Assisted Security Plan via Ollama
rflow manifest generate --ai-assist --ai-provider ollama

rflow version bump

Bumps the version, updates .version state, and creates signed git commits/tags.

bash

rflow version bump [patch|minor|major] [flags]

Flags:
  --app-repo string      Path to the application repository to tag in sync
  --dry-run              Simulate changes without modifying files or git
  --kv string            Azure Key Vault name to fetch GPG keys from
  --key-secret string    Secret name for GPG Private Key (requires --kv) (default: gpg-private-key)
  --pass-secret string   Secret name for GPG Passphrase (requires --kv) (default: gpg-passphrase)

Examples

bash

# Bump patch version
rflow version bump patch

# Bump minor version with Azure Key Vault integration
rflow version bump minor --kv my-vault --key-secret my-key --pass-secret my-pass

# Dry run to see what would change
rflow version bump major --dry-run

rflow build

Builds and pushes container images defined in the manifest.

bash

rflow build --manifest <path> --app-dir <path> [flags]

Flags:
  --manifest string    Path to release-manifest.yaml (required)
  --app-dir string     Path to application repository root (required)
  --push               Push images to registry after build (default: true)

Example

bash

rflow build --manifest manifests/release-manifest.yaml --app-dir ../app

rflow sbom generate

Generates Software Bill of Materials (SBOM) for all images defined in the manifest using Syft.

bash

rflow sbom generate [flags]

Flags:
  --manifest string    Path to release manifest (default: manifests/release-manifest.yaml)

Example

bash

# Uses default manifest path
rflow sbom generate

# Or specify custom manifest
rflow sbom generate --manifest manifests/releases/release-v1.0.0.yaml

rflow scan images

Scans all images in the manifest for vulnerabilities using Trivy. Results are written to the security/scans directory.

bash

rflow scan images [flags]

Flags:
  --manifest string         Path to release manifest (default: manifests/release-manifest.yaml)
  --service, -s string      Scan specific service only
  --verbose, -v             Show detailed tool output
  --report-location string  Report storage location: local|remote (default: local)
  --report-git-url string   Git URL for remote reporting (overrides config)
  --report-git-branch string Git branch for remote reporting (default: main)
  --report-git-path string  Path in git repo for reports (default: scans/)

Examples

bash

# Scan all images (uses default manifest)
rflow scan images

# Scan only the API service
rflow scan images --service api
# or
rflow scan images -s api

# Scan with verbose output
rflow scan images --verbose
# or
rflow scan images -v

# Scan and push reports to remote git
rflow scan images --report-location remote --report-git-url https://github.com/org/repo.git

rflow sign images

Signs all images in the manifest using Cosign. This establishes the root of trust.

bash

rflow sign images --key <key-ref> [flags]

Flags:
  --manifest string    Path to release manifest (default: manifests/release-manifest.yaml)
  --key string         Cosign key reference (e.g., azurekms://...) (required)
  --tlog-upload        Upload to transparency log (default: false)

Examples

bash

# Sign with Azure Key Vault (uses default manifest)
rflow sign images --key azurekms://my-vault.vault.azure.net/keys/signing-key

# Sign with Kubernetes secret
rflow sign images --key k8s://default/cosign-key

# Sign with local key file
rflow sign images --key cosign.key

# Sign and upload to transparency log
rflow sign images --key azurekms://... --tlog-upload

rflow verify

Verifies the integrity and compliance of a release. Checks signatures, SBOM presence, and policy adherence.

bash

rflow verify --key <key-ref> [flags]

Flags:
  --manifest string    Path to release manifest (default: manifests/release-manifest.yaml)
  --key string         Cosign key reference (required)
  --out string         Directory to write verification evidence (default: security/cosign)

Example

bash

# Verify with Azure Key Vault public key
rflow verify --key azurekms://my-vault.vault.azure.net/keys/signing-key

# Verify with local public key file
rflow verify --key pubkey.pem

# Verify and save evidence to custom directory
rflow verify --key pubkey.pem --out security/verification

rflow promote

Promotes a verified release to a downstream environment. This validates all gates again and retags the immutable images.

bash

rflow promote --version <version> --env <env> [flags]

Flags:
  --version string    Release version to promote (e.g. 0.1.29) (required)
  --env string        Target environment: dev|staging|prod (required)
  --dry-run           Plan only; make no changes (default: false)

Examples

bash

# Promote to staging
rflow promote --version 1.0.0 --env staging

# Promote to production
rflow promote --version 1.0.0 --env prod

# Dry run to see what would happen
rflow promote --version 1.0.0 --env prod --dry-run

rflow doctor

Checks your environment for required dependencies and configuration health.

bash

rflow doctor

This command verifies:

Required tools are installed (git, docker, trivy, syft, cosign)
Tools are accessible in PATH
Configuration file exists and is valid
Git repository state

rflow config init-secrets

Initializes the secrets configuration in release.yaml (e.g., for Azure Key Vault).

bash

rflow config init-secrets --provider azure-keyvault --vault <name>

rflow keys generate gpg

Generates a new GPG key pair locally and securely uploads the private key, public key, key ID, and passphrase to the configured Key Vault.

bash

rflow keys generate gpg --name "<name>" --email "<email>" [flags]

Flags:
  --name string    Real name for the GPG key (required)
  --email string   Email address for the GPG key (required)
  --prefix string  Prefix for secret names in the vault (default: rflow)

Example

bash

rflow keys generate gpg --name "John Doe" --email "john@example.com"

rflow completion

Generates shell completion scripts for Bash, Zsh, Fish, or PowerShell.

bash

rflow completion <shell> [flags]

Shells: bash, zsh, fish, powershell

Automatic Installation

bash

rflow completion zsh --install

Manual Installation

bash

# Zsh
source <(rflow completion zsh)

# Bash
source <(rflow completion bash)

# Fish
rflow completion fish | source

# PowerShell
rflow completion powershell | Out-String | Invoke-Expression

rflow platform

Inspect and interact with CI/CD platform integrations (ADO/GitHub/GitLab/etc.).

rflow platform detect

Detect which CI/CD platform rflow is running under.

bash

rflow platform detect [flags]

Flags:
  --platform string   Platform to use: auto|ado|github|gitlab|generic (default: auto)

rflow platform env

Print normalized CI/CD environment details (branch, sha, build id, etc.).

bash

rflow platform env [flags]

Flags:
  --platform string   Platform to use: auto|ado|github|gitlab|generic (default: auto)

rflow report

Generate release reports (internal/external) from manifests + notes + security data.

bash

rflow report --version <version> [flags]

Flags:
  --version string    Release version to report on (e.g. 0.1.29) (required)
  --format string     Report output format: md|html|json (default: md)
  --out string        Write report to a file (default: stdout)

Example

bash

rflow report --version 0.1.29 --format md --out release-report-0.1.29.md

rflow gui

Launch the local ReleaseFlow web interface for a visual overview of your releases, policies, and environments.

bash

rflow gui [flags]

rflow serve

Start a long-running ReleaseFlow server, allowing external integrations and agents to interact with the orchestration engine via an API.

bash

rflow serve [flags]

rflow notes

Generate, manage, and publish release notes from commit history or defined templates.

bash

rflow notes [flags]

rflow questions

Launch an interactive FAQ and Getting Started guide within the terminal.

bash

rflow questions [flags]

Workflows & Examples

Basic Release Workflow

A complete end-to-end release workflow from manifest generation to promotion.

release.sh

bash

#!/bin/bash
set -e

# 1. Generate release manifest with automatic version bump
rflow manifest generate --bump patch

# 2. Build container images (uses default manifest: manifests/release-manifest.yaml)
rflow build --manifest manifests/release-manifest.yaml --app-dir .

# 3. Generate SBOMs (uses default manifest)
rflow sbom generate

# 4. Scan for vulnerabilities (uses default manifest)
rflow scan images

# 5. Sign images (uses default manifest)
rflow sign images --key azurekms://my-vault.vault.azure.net/keys/signing-key

# 6. Verify release meets all policies (uses default manifest)
rflow verify --key azurekms://my-vault.vault.azure.net/keys/signing-key

# 7. Promote to staging
VERSION=$(cat .version)
rflow promote --version "$VERSION" --env staging

CI/CD Integration

Integrate ReleaseFlow into your CI/CD pipeline for automated releases.

GitHub Actions Example

.github/workflows/release.yml

yaml

name: Release

on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Install ReleaseFlow
        run: |
          curl -fsSL https://get.releaseflow.io | sh
      
      - name: Generate Manifest
        run: rflow manifest generate --bump patch
      
      - name: Build Images
        run: rflow build --manifest manifests/release-manifest.yaml --app-dir .
      
      - name: Security Scan
        run: |
          rflow sbom generate
          rflow scan images
          rflow sign images --key ${{ secrets.COSIGN_KEY }}
      
      - name: Verify
        run: rflow verify --key ${{ secrets.COSIGN_PUBLIC_KEY }}
      
      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: release-manifest
          path: manifests/**/*.yaml

Azure DevOps Pipeline Example

azure-pipelines.yml

yaml

trigger:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: Bash@3
    displayName: 'Install ReleaseFlow'
    inputs:
      targetType: 'inline'
      script: |
        curl -fsSL https://get.releaseflow.io | sh
  
  - task: Bash@3
    displayName: 'Generate Release Manifest'
    inputs:
      targetType: 'inline'
      script: |
        rflow manifest generate --bump patch
  
  - task: Bash@3
    displayName: 'Build and Secure Release'
    inputs:
      targetType: 'inline'
      script: |
        rflow build --manifest manifests/release-manifest.yaml --app-dir .
        rflow sbom generate
        rflow scan images
        rflow sign images --key $(COSIGN_KEY)
        rflow verify --key $(COSIGN_PUBLIC_KEY)

Multi-Service Releases

ReleaseFlow handles complex multi-service applications with ease.

bash

# release.yaml
services:
  - name: frontend
    dockerfile: ./frontend/Dockerfile
    context: ./frontend
    image:
      repository: myapp-frontend
  
  - name: api
    dockerfile: ./api/Dockerfile
    context: ./api
    image:
      repository: myapp-api
  
  - name: worker
    dockerfile: ./worker/Dockerfile
    context: ./worker
    image:
      repository: myapp-worker

# All services are processed together
rflow manifest generate
rflow build --manifest manifests/releases/release-v1.0.0.yaml
rflow sbom generate --manifest manifests/releases/release-v1.0.0.yaml
rflow scan images --manifest manifests/releases/release-v1.0.0.yaml

Environment Promotion

Promote releases through your environment pipeline safely and auditably.

bash

# Development → Staging → Production workflow

# 1. Release is created and verified in dev
rflow manifest generate --bump patch
rflow build --manifest manifests/release-manifest.yaml --app-dir .
rflow verify --key pubkey.pem

# 2. Promote to staging (retags images: api:1.0.0 → api:staging)
VERSION=$(cat .version)
rflow promote --version "$VERSION" --env staging

# 3. After staging validation, promote to production
rflow promote --version "$VERSION" --env prod

Security & Compliance

AppSec AI Pipeline

ReleaseFlow integrates native AI capabilities to enhance your security posture, tracking AI-generated code provenance, enforcing agent runtime boundaries, and simulating autonomous attacks.

Dynamic Red-Teaming (PyRIT)

Gated behind the Business Edition, you can provision PyRIT to autonomously sandbox and red-team your release artifacts to identify novel evasion techniques.

Agent Runtime Guardrails

Define strict operational boundaries for AI agents executing within your pipeline, preventing hallucinated dependencies or unauthorized network access.

AI-BOM & Provenance

Extend your standard software bill of materials with explicit AI artifact tracking (aiArtifacts) to record prompt templates, foundation model IDs, and local training data hashes.

SBOM Generation

Software Bill of Materials (SBOM) provides transparency into the components that make up your container images.

bash

# Generate SPDX format SBOMs (uses default manifest)
rflow sbom generate

# SBOMs are saved to security/sbom/
# Each image gets its own SBOM file:
# - security/sbom/api-v1.0.0.spdx.json
# - security/sbom/frontend-v1.0.0.spdx.json

SBOMs include:

All packages and dependencies
Package versions and licenses
File system contents
Build metadata

Vulnerability Scanning

Automated vulnerability scanning using Trivy identifies security issues before deployment.

bash

# Scan all images (uses default manifest)
rflow scan images

# Scan results are saved to security/scans/
# Reports include:
# - CVE IDs and descriptions
# - Severity levels (CRITICAL, HIGH, MEDIUM, LOW)
# - Affected packages
# - Remediation recommendations

Policy-Based Blocking

Configure your release.yaml to block releases with critical vulnerabilities:

yaml

security:
  policies:
    - type: vulnerability
      severity: CRITICAL
      action: block
    - type: vulnerability
      severity: HIGH
      action: warn
      requireJustification: true

Image Signing

Cryptographically sign your container images to establish trust and prevent tampering.

bash

# Sign with Azure Key Vault (recommended for production, uses default manifest)
rflow sign images --key azurekms://my-vault.vault.azure.net/keys/signing-key

# Sign with Kubernetes secret
rflow sign images --key k8s://default/cosign-key

# Sign with local key file
rflow sign images --key cosign.key

Verifying Signatures

bash

# Verify image signatures (uses default manifest)
rflow verify --key pubkey.pem

# Or verify directly with cosign
cosign verify --key pubkey.pem myregistry.io/my-app:1.0.0

Policy Gates

Define and enforce security policies that must be satisfied before promotion.

yaml

# release.yaml
security:
  policies:
    # Block critical vulnerabilities
    - type: vulnerability
      severity: CRITICAL
      action: block
    
    # Require justification for high severity
    - type: vulnerability
      severity: HIGH
      action: warn
      requireJustification: true
    
    # Require all images to be signed
    - type: signature
      required: true
    
    # Require SBOMs
    - type: sbom
      required: true

The rflow verify command checks all policies and fails if any are not met.

Troubleshooting

Common Issues

Missing Dependencies

Problem: Commands fail with "command not found" errors.

Solution: Run rflow doctor to identify missing tools and install them.

Docker Not Running

Problem: Build commands fail with Docker connection errors.

Solution: Ensure Docker daemon is running: docker ps

Authentication Failures

Problem: Cannot push images to registry.

Solution: Ensure registry credentials are set in environment variables or configured in release.yaml.

Version Conflicts

Problem: Version bump fails due to existing tags.

Solution: Use --dry-run to preview changes, or manually resolve git tag conflicts.

Error Messages

"Failed to load config"

Ensure release.yaml exists in the current directory or specify with --config.

"Policy gate failed: CRITICAL vulnerabilities found"

Your release contains critical vulnerabilities. Review scan reports in security/scans/ and remediate before proceeding.

"Image signature verification failed"

The image signature doesn't match the provided public key. Ensure you're using the correct key and the image hasn't been tampered with.

Debugging Tips

Use --verbose flag for detailed output: rflow scan images --verbose
Check manifest files in manifests/releases/ for release state
Review security reports in security/scans/ and security/sboms/
Use rflow doctor to verify environment setup
Enable JSON output for machine parsing: rflow --json manifest generate

Frequently Asked Questions

Can I use ReleaseFlow with existing CI/CD pipelines?

Yes! ReleaseFlow is CI/CD agnostic and can be integrated into any pipeline. See the CI/CD Integration section for examples.

How do I handle secrets and credentials?

Use environment variables or your CI/CD platform's secret management. Never commit secrets to your repository.

Can I customize the manifest format?

The manifest schema is standardized, but you can extend it with custom metadata fields as needed.

What if I need to rollback a release?

ReleaseFlow maintains immutable manifests for all versions. Simply promote a previous version using rflow promote --version <previous-version> --env <env>.

How do I integrate with Kubernetes?

ReleaseFlow generates manifests that can be consumed by Kubernetes deployment tools. The signed images can be verified at deployment time using admission controllers.

Need help? Check the Troubleshooting section or open an issue on GitHub.