Prefect Deployments Toolkit

A lightweight CLI toolkit for managing Prefect deployment lifecycles in CI/CD pipelines. It detects deployments that were added, modified, or removed between two git references, and applies (creates, updates, or deletes) those deployments against Prefect Cloud or a self-hosted Prefect server — via either the Prefect CLI or direct REST API calls.

Built for teams running many Prefect flows out of a monorepo, where each deployment is defined in its own YAML file alongside a shared prefect_base.yaml, and CI needs to figure out which deployments actually changed before re-registering them.

Features

• Change detection — diff deployments between two git refs (a merge request source vs. target branch, or HEAD~1 vs. HEAD after a merge) and get back exactly which deployments were added, modified, or removed.
• Unified push / pull-request logic — one code path handles both pull_request (compare local files against a fetched base branch) and push/pull_request_target (compare HEAD~1 against HEAD) event styles.
• Dual deploy backends — apply deployments using the prefect CLI as a subprocess, or bypass it entirely with direct REST API calls for faster, more controllable deploys. Both backends work against Prefect Cloud and self-hosted/OSS Prefect servers.
• Dev/prod environment overrides — automatic name prefixing, work pool substitution, and schedule pausing for dev environments.
• Concurrent deployment application — apply multiple deployments in parallel with clean, non-interleaved log output per deployment.
• Duplicate deployment name detection — warns (or optionally cleans up) when the same deployment name resolves to more than one flow.

Installation

pip install prefect-deployments-toolkit

Requires Python >= 3.9.

Usage

1. Detect modified deployments

python -m prefect_deployments_toolkit.get_modified_deployments \
  --modified-by push \
  --base-ref main \
  --deployments-dir deployments

Prints a comma-separated list of changed deployment names to stdout, and (if running inside GitHub Actions) writes DEPLOYMENT_NAMES, NEW_OR_MODIFIED_DEPLOYMENT_NAMES, and REMOVED_DEPLOYMENT_NAMES to GITHUB_ENV.

--modified-by accepts:

• pull_request — compares your local working tree against the fetched base branch (use during an open MR/PR).
• push or pull_request_target — compares HEAD~1 against HEAD (use after a merge to a protected branch).

2. Apply deployments

python -m prefect_deployments_toolkit \
  --deployment-names "flow_a,flow_b" \
  --enable-schedule false \
  --tag dev \
  --reference feature-branch-1 \
  --repo-name my-flows-repo \
  --custom-image "" \
  --deployments-dir deployments \
  --dev-work-pool my-dev-work-pool \
  --backend rest \
  --enforce-unique-deployment-names false

Expected Repository Layout

deployments/
├── prefect_base.yaml # shared config merged into every deployment
├── flow_a.yaml
├── flow_b.yaml
└── ...

Each deployment YAML file must declare a deployments: list with at least a name and entrypoint key, following the standard Prefect deployment YAML schema.

Backends

Both backends work against Prefect Cloud (api.prefect.cloud) and self-hosted/OSS Prefect servers — the target is determined entirely by PREFECT_API_URL.

Environment Variables

Neither PREFECT_API_KEY nor PREFECT_API_AUTH_STRING is required if your self-hosted Prefect server has no authentication configured — only PREFECT_API_URL is mandatory in every setup.

License

Licensed under PolyForm Noncommercial 1.0.0. You may view, use, and modify this software for noncommercial purposes. Commercial use — including building products, services, or automation on top of it — requires a separate license. Contact kwolski@dyvenia.com for commercial licensing inquiries.

Contributing

Issues and pull requests are welcome for noncommercial use cases. Please open an issue before submitting a large PR to discuss scope.