Skip to content

ci

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

ci

README.md

CI / GitOps examples

These files show a register → ingest → diff (policy gate) → verify loop you can drop into a pipeline. They mirror examples/quickstart and the flightdeck-quickstart-verify script, but stop before promotion so a pull request can fail when the active policy would reject the candidate.

Policy gate exit code

flightdeck release diff accepts --fail-on-policy: after printing the diff, the command exits 1 when the active policy does not pass (same semantics as a failed release promote, without writing the ledger).

Use this flag in CI so a red build means “unsafe to ship under current policy,” not only “CLI error.”

ledger_gate.py (recommended)

Canonical cross-platform gate (used by .github/workflows/ci.yml). Runs the CLI as python -m flightdeck.cli.main from the same interpreter that executes the script (the uv devenv on CI, or python after pip install flightdeck-ai).

Environment:

Variable Required Meaning
WORKSPACE yes Dedicated throwaway directory for flightdeck.yaml + SQLite (deleted and recreated each run)
QUICKSTART_ROOT yes Path to examples/quickstart (or your own copy of those fixtures)
FD_PROJECT — Ignored by ledger_gate.py (kept on env in workflows for documentation only).

Policy for the diff step is ledger-gate-policy.yaml next to this README (not quickstart/policy.yaml): quickstart candidate cost is ~$5/run while quickstart policy caps $4, so --fail-on-policy would fail there by design.

ledger-gate.sh is a thin exec …/ledger_gate.py wrapper for local bash users.

Example (monorepo with uv):

export WORKSPACE="$(mktemp -d)"
export QUICKSTART_ROOT="$PWD/examples/quickstart"
uv run python examples/ci/ledger_gate.py

Example (PyPI install):

pip install "flightdeck-ai>=1.2.0"
export WORKSPACE="$(mktemp -d)"
export QUICKSTART_ROOT=/path/to/flightdeck/examples/quickstart
python /path/to/flightdeck/examples/ci/ledger_gate.py

GitHub Actions

Copy a workflow from github-actions/ into .github/workflows/ in your repository and adjust paths, Python version, and FlightDeck version pins.

File Use when
policy-gate-monorepo.yml This repository (or a fork): uv sync + uv run python examples/ci/ledger_gate.py.
policy-gate-pypi.yml Another repo: install flightdeck-ai from PyPI and sparse-checkout upstream examples/quickstart for fixtures (pin the checkout ref to match your installed version when possible).
promote-approval-twostep.yml Example workflow_dispatch job that runs promote-request and logs request_id for a follow-up confirm.

Promoting from CI

flightdeck release promote is intentionally not in the gate script: many teams run diff/verify on every PR and only promote from a protected branch or manual workflow with secrets and review. If you automate promote, reuse the same workspace (or a trusted replica), set policy explicitly, and pass a non-empty --reason (for example the Git run URL).

Human approval (promotion_requires_approval)

When promotion_requires_approval: true in flightdeck.yaml, direct release promote / POST /v1/promote are rejected until a pending row is confirmed:

  1. flightdeck release promote-request … (or POST /v1/promote/request) — prints request_id=… on success; policy must pass for the request to be created.
  2. flightdeck release promote-confirm <request_id> --approval-reason "…" (or POST /v1/promote/confirm) — applies the promote; policy is evaluated again on confirm.

Shell helper (bash): promote_with_approval.sh — request and confirm subcommands wrap the CLI.

GitHub Actions sketch: github-actions/promote-approval-twostep.yml — workflow_dispatch runs request; run confirm from a separate gated job or locally after review, passing the captured request_id.

Related