Skip to content

FlowForge v1.0.0

Choose a tag to compare

View all tags
@Abolfazlrwm Abolfazlrwm released this 25 Oct 13:49
· 169 commits to 1fc077cdd06e7d8749f10523505c5f64498819fb since this release
v1.0.0
37013ed

FlowForge v1.0.0 — release notes

Approved for release. The owner approved tagging and publishing v1.0.0 on
2026-10-25; that approval is the gate in owner decision 2026-10-22, recorded in
DECISIONS.md. The cut procedure is
RELEASE_CHECKLIST.md.

Summary

FlowForge is a distributed workflow orchestration engine for DAG-shaped jobs,
built on Django 5.2 LTS, PostgreSQL, RabbitMQ and Redis. It makes the hard parts
of distributed execution explicit — leases, fencing tokens, a transactional
outbox and at-least-once delivery — instead of hiding them behind a task
decorator.

v1.0.0 is the first stable release. It is the culmination of Phases 0–10
(shipped as v0.1.0 … v0.11.0) plus Phase 11, Production Hardening: the
operational surface that makes the engine deployable and operable — a security
review, safe migrations, Kubernetes, backups, high availability, an end-to-end
suite, and a signed, SBOM'd supply chain.

The 1.0 stability commitment was an owner decision, and it has been made.
Tagging v1.0.0 signals a SemVer stability promise for the REST API and the
public contract; the owner approved that promise on 2026-10-25.

What FlowForge gives you

  • Describe, validate, publish, trigger a workflow over a versioned REST API,
    with a Python SDK (flowforge-client) and a flowforge CLI.
  • Correct distributed execution. A scheduler promotes dependency-satisfied
    tasks into a transactional outbox; a publisher delivers to RabbitMQ with
    publisher confirms; a worker claims each task run with a fencing token, runs a
    trusted handler, writes the durable outcome, and only then acks.
  • Reliability. Bounded retries with exponential backoff and full jitter, a
    terminal DEAD state with manual requeue, lease recovery that bumps the fencing
    token, and a failure model (docs/architecture/failure-model.md) that maps
    every failure mode to a test that proves the recovery.
  • Multi-tenancy and security. Per-organization scoping by construction
    (ADR-014), RBAC, hashed/scoped/rotatable API keys, an append-only audit log
    protected by a database trigger, and secret redaction.
  • Observability. Correlation ids and traces that follow a run across every
    process, per-process Prometheus metrics, and Grafana dashboards as code.
  • Operability. Docker Compose and a Kubernetes Helm chart, a backup/restore
    runbook with a CI restore drill, high-availability guidance, and a signed,
    SBOM'd, digest-pinned container image.

New since v0.11.0 (Phase 11 — Production Hardening)

  • Security review — gitleaks over the full history with push protection;
    Trivy image scanning with a CRITICAL gate; a STRIDE threat model; an
    overhauled SECURITY.md with a private disclosure process.
  • Migration safety — a CI test that upgrades from the v0.9.0 schema with
    data present, and a per-migration zero-downtime classification
    (docs/deployment/migrations.md).
  • Kubernetes — a Helm chart and rendered manifests, validated in CI with
    helm lint and kubeconform -strict, plus an on-demand kind smoke test.
  • Backup and restore — a runbook and a CI drill that dumps, wipes, restores,
    checks row counts, and runs a workflow end to end.
  • High availability — docs/deployment/ha.md, honest about what is proven
    and what is operator-validated.
  • End-to-end suite — tests/e2e/ drives the REST API, SDK and CLI against
    the Compose stack in CI.
  • Supply chain — a CycloneDX SBOM attached to each release, keyless cosign
    signing recorded in Rekor, build provenance, and a digest-pinned base image.
  • Documentation site — the MkDocs site is published to GitHub Pages from
    main.

Install

git clone https://github.com/Abolfazlrwm/flowforge.git
cd flowforge
docker compose up --build -d
curl -s http://localhost:8000/health/ready/   # {"status": "ready", ...}

Or the Python SDK / CLI:

pip install ./sdk          # flowforge-client, no runtime dependencies
export FLOWFORGE_URL=http://localhost:8000
export FLOWFORGE_TOKEN=<token>
flowforge trigger my-workflow --version 1

Verify this release

The image is signed; verify without a key. CI publishes the image as main and
main-<commit-sha> (there is no per-version registry tag), so resolve the commit
the tag points at:

IMAGE="ghcr.io/abolfazlrwm/flowforge:main-$(git rev-list -n1 v1.0.0)"

cosign verify \
  --certificate-identity-regexp 'https://github.com/Abolfazlrwm/flowforge/.github/workflows/ci.yml' \
  --certificate-oidc-issuer-regexp 'https://token.actions.githubusercontent.com' \
  "$IMAGE"

For a reproducible deploy, pin the digest rather than the tag
(docker inspect --format='{{index .RepoDigests 0}}' "$IMAGE"). The signature
covers the digest, so a digest reference verifies the same way.

The release carries flowforge-sbom.cdx.json, a CycloneDX inventory of every
component in the image.

Honest scope

  • At-least-once, never exactly-once. Duplicate suppression is best-effort
    (idempotency keys + fencing tokens + dispatch_id); two concurrent executions
    of the same key can both run.
  • No arbitrary user code. Task handlers are a fixed, trusted set; a task
    definition is data, not code.
  • Single writable PostgreSQL primary. The app has no read/write splitting;
    HA needs a standby to promote (see docs/deployment/ha.md).
  • Full list: docs/development/PROGRESS.md → Known limitations.

Upgrade notes

Every migration is additive (no table rewrite), so a rolling upgrade is safe:
back up, run manage.py migrate as a one-shot job, then roll the new pods.
See docs/deployment/migrations.md. No action is required to upgrade from
v0.11.0 beyond the migration.

Assets 3
Loading