How to Roll Back Deployments in Prefect with Deployment Versioning

Watch the deployment versioning walkthrough video to learn how rollbacks works in the UI.

Today we're introducing deployment versioning in Prefect, a smarter way to manage changes, track performance, and recover quickly when something goes wrong.

If you've ever wished you could just "undo" a deployment or see exactly what code commit ran last week in production, this feature is for you.

Why This Matters

Before this release, updating a deployment in Prefect meant overwriting it. Once a new version was pushed, there was no built-in safety net. If something broke, the only recovery path was to manually revert code in Git or rebuild and redeploy through CI.

That workflow works until it stops being reliable. It slows teams down, clutters your Git history and introduces risk when rolling out changes.

Deployment versioning solves that by making every update traceable and reversible.

What Deployment Versioning Enables

With deployment versioning, you get better control over what runs, when it runs, and how to go back when something breaks.

• Recording complete versions automatically. Every time you update a deployment, Prefect saves the Git commit SHA (if available), Docker reference (if used), infrastructure settings, and all runtime configuration. There’s no extra setup required.
• Showing a full version history in the UI. You can browse past versions of any deployment and inspect when they were created, what ran, and how they performed.
• Tracking metrics per version. Prefect links each version to its own run history, so you can spot regressions in success rate or runtime without digging.
• Letting you roll back instantly. If something breaks, just click “Roll back” in the UI. You’re back to a working state with no Git reverts or CI pipeline runs.

These capabilities give you clearer visibility and safer control over your deployments, no matter where or how they're running.

How It Works

Every deployment in Prefect Cloud is versioned. A new version is created automatically whenever you update a deployment using the CLI, Python deployment methods, the UI, or tools like Terraform.

Prefect also tracks Git metadata, like the commit SHA, when the update happens in a Git-aware environment such as GitHub Actions, the CLI, or Python. Deployments created with Terraform or the prefect-cloud package are still versioned, but Git information is not captured.

Each version includes the full deployment configuration, including parameter defaults, tags, pull steps, job variables, and concurrency limits.

In the UI, you can view version history and roll back to any earlier version. Just select "Roll back" and the next run will use it.

To learn how to pin a specific Git SHA or use a Docker image digest, see the deployment versioning documentation.

Rolling Back After Breaking Your Workflow

Let’s say you deploy a flow with updated logic for cost allocation. After pushing to production you notice workflows start failing. You added currency symbols to the cost values, forgetting that the column in your destination table expects floats, not strings. You need to fix your code and add a test to stop this mistake from happening in the future, but this workflow runs once per minute and any missed data is a problem for your team.

With deployment versioning, you don’t have to revert your Git repo or trigger a full rebuild. Instead:

1. Open the Deployment page in the UI and click on the Version tab
2. Find the last known good version
3. Click "Roll back"

You're now back to the version that worked. No new commits, no waiting on CI, no messy history.

Key Details and Tips

Deployment versioning gives you a reliable rollback experience, but there are a few important caveats to know:

• Code pinning happens in pull_ steps and job_variables. These are the fields that define exactly what code Prefect will run. To ensure accurate rollback, use a commit SHA in your Git pull_steps or a digest in your Docker job_variables . This is the only way to tie a deployment version to the specific code version that was present at deployment time.
• Rollbacks are only as precise as your references. If you reference a Git branch or Docker tag, the code that reference represents can change over time. Rollbacks will still work, but they will always run the latest code on that branch or that tag. Use Git SHAs and image digests for guaranteed consistency.
• Git-aware environments provide richer visibility in the UI. Prefect captures commit and repository metadata when you deploy from any Git-aware environment. For GitHub, GitLab, Bitbucket, and Azure DevOps, this includes a clickable link to the exact commit, along with the platform’s logo. For other Git sources, Prefect still shows the metadata, but links only to the repository and displays a generic icon.

For more information on how to configure these fields and get the most out of deployment versioning, see the documentation.

Try It Out

Deployment versioning is available to Prefect Cloud users with Prefect versions 3.4.1 and above.

Visit the docs to learn more about deployment versioning or sign up now and get started for free.

We hope this gives you a smoother, safer way to manage changes.

Have questions? Join our community Slack.