Retention Policies

Every preview deployment is a snapshot. Code at a moment in time. Environment variables at a moment in time. If you launched the Foundry six months ago, the preview for the branch that built it is still sitting in Vercel, accessible, indexed under your team. The code in it might still be valid. The secrets in it might still work. The data it served might have been replaced everywhere else by something different, but that deployment doesn't know.

Retention policies tell Vercel when to garbage-collect old deployments. You set different windows for canceled builds, errored builds, preview deployments, and production. Vercel exempts a protected set (the last few deployments, anything with a live alias, the latest preview per active branch). Everything else gets deleted on schedule.

The point isn't disk space. Vercel handles that without your help. The point is reducing the surface area of old previews that might leak, might still hold deprecated env vars, or might serve content you'd rather not have indexed.

Outcome

Saturday has retention policies in place: canceled and errored deployments are pruned after 7 days, previews after 30 days, production deployments after 90 days.

What Vercel Won't Delete

Before you set the policies, know what stays no matter what:

• The last 10 deployments created (regardless of status)
• The last 20 production deployments in Ready state
• The last 20 non-production deployments in Ready state
• Any deployment with a production alias
• Any deployment with a custom alias (your custom domain mapping)
• The latest preview deployment for each currently-active Git branch
• Branch-alias targets for custom environments

Anything past those guards is fair game.

Hands-on exercise 5.3

One settings page. Four input fields. Five minutes total.

Requirements:

1. Open Saturday > Settings (the Security sub-page, or wherever Deployment Retention Policy lives in the current dashboard layout)
2. Set the Canceled Deployments retention to 7 days (or the nearest preset the dropdown offers). These are deployments where the build was aborted before completion. They're rarely useful past a week.
3. Set the Errored Deployments retention to 7 days. Same reasoning. If a build is going to be useful for debugging, you debugged it that week.
4. Set the Preview Deployments retention to 30 days. A month is enough for active feature branches to stay around. Past that, the branch is either merged (so the preview is irrelevant) or stale (so the preview is misleading).
5. Set the Production Deployments retention to 90 days. A quarter of rollback history is sensible for most teams. If you have stricter compliance reasons, raise it; if you're confident in your forward-only deploys, lower it.
6. Save the policy.

Implementation hints:

• Retention starts counting from the deployment's creation date, not its last access. A preview that's six months old gets deleted at the next sweep even if you visited it yesterday.
• Vercel doesn't delete instantly when a deployment crosses the threshold. A background job typically marks it for deletion within 48 hours, and a freshly enabled policy can take a few days to start sweeping.
• Successfully built deployments that get deleted by policy can be restored within 30 days (a soft delete). Errored or canceled deployments may be hard-deleted on a shorter schedule. So if you have an errored build you want to keep for a postmortem, save the logs before you set retention to 7 days.
• The defaults are generous on purpose; Vercel wants you to keep your history if you want it. If you want strict cleanup, you have to ask for it.

Try It

Open Saturday > Deployments and look at the list. You should see all your historical deployments, every preview, every redeploy, every commit that landed on main.

After your retention policy has been in effect for a couple of days (the sweep isn't instant), check back. Old previews from branches you've already deleted should be gone. The list should be visibly shorter.

If you want to verify before the sweep runs, look at the timestamps on the oldest deployments visible. Anything older than your retention windows should be flagged for cleanup (some dashboards show a "Pending deletion" badge). After the sweep, those rows disappear.

Done-When

• Saturday > Settings > Security > Deployment Retention Policy is configured with four values
• Canceled and Errored are both set to 7 days (or shorter)
• Preview is set to 30 days (or shorter)
• Production is set to 90 days (or longer if compliance requires)
• Within a couple of days of the sweep, the Deployments list reflects the new policy

Troubleshooting

I set a policy and old deployments are still there.

The sweep isn't instant. Deployments are typically marked for deletion within 48 hours of crossing the threshold, and a brand-new policy can take a few days to get going. Also confirm the deployments you're seeing aren't in the protected set (last 10, latest per branch, etc.). Those won't be deleted no matter the policy.

I want a preview I deleted back.

If it was a Ready-state preview, you have 30 days to restore it from Settings > Security > Recently Deleted. Errored and canceled deployments may be garbage-collected sooner, so don't count on those coming back.

I want retention even tighter (3 days, say).

The retention dropdown offers preset windows rather than a free-form number, so pick the shortest preset that fits. Just remember that very short windows will occasionally cost you a preview you'd have wanted for a postmortem. The middle ground for most teams is the one above.

Solution

The state of the policy:

Settings > Security > Deployment Retention Policy
  Canceled:     7 days
  Errored:      7 days
  Preview:      30 days
  Production:   90 days

No code change in the repo. As with the rest of this section, the value is in the team-wide hygiene rather than in any artifact you ship.

That wraps Section 5. Sections 5 controls work for Pro teams; Section 6 is where Enterprise unlocks the rest, SSO, audit logs, network isolation. If you're not on Enterprise, you can read along to understand what those controls do. If you are, the next five lessons are your homework.