Managing Vercel preview branch cleanup

How cleanup works

When you use Neon's Vercel integration, a Neon database branch is created for each Git branch that has a preview deployment. These are called preview branches. The two integration types handle cleanup of these branches differently:

• Vercel-Managed Integration: Neon deletes a preview branch when its last associated Vercel deployment is deleted. This can happen in two ways:
  • Vercel automatically removes it through its deployment retention policy (which can take months).
  • You manually delete the Vercel deployment (which triggers immediate Neon cleanup)
• Neon-Managed Integration: Neon deletes a preview branch when the corresponding Git branch no longer exists in your repository. This is triggered the next time a preview deployment is created.

Why branches aren't cleaned up immediately

If you're using the Vercel-Managed integration, you might expect preview branches to be deleted when you close a PR or delete a Git branch. That doesn't happen because cleanup is tied to deployment deletion, not Git branch deletion. Manually deleting a Vercel deployment triggers immediate Neon branch cleanup, but most teams rely on Vercel's automatic retention, which follows this timeline:

1. Vercel retains preview deployments for 6 months by default. As of October 2025, Vercel's default retention for pre-production deployments is 180 days. The clock starts when the deployment is created, not when the PR is closed.
2. Vercel's cleanup job runs asynchronously. After the retention period expires, Vercel deletes the deployment in a batch process. This typically happens within hours to days of the expiration date, not instantly. Vercel offers a 30-day recovery window to restore deleted deployments, but this does not delay cleanup for connected integrations.
3. Neon deletes the branch when Vercel deletes the deployment. Neon receives a cleanup webhook and removes the corresponding preview branch immediately.

In the worst case (a deployment created moments before the PR is closed), this means up to ~6 months before the Neon branch is automatically deleted.

Retention exceptions

Vercel keeps a minimum number of recent deployments regardless of your retention settings. See Vercel's retention exceptions for details. Neon branches associated with these retained deployments won't be automatically cleaned up. Use the GitHub Action approach for those.

These exceptions protect deployments, not branches. A single branch can have multiple deployments, so the number of protected branches depends on how deployments are distributed across them.

The following screenshot shows Vercel's default retention policy settings, where pre-production deployments are set to 180 days:

Reducing Vercel's retention policy

Lowering the retention period reduces how long Vercel keeps deployments before deleting them. This is most effective for projects with many preview deployments. For projects with low deployment activity, retention exceptions may prevent automatic cleanup entirely, and the GitHub Action approach is a better option.

To adjust your retention settings:

1. Open your Vercel project dashboard
2. Go to Settings → Security
3. Scroll to Deployment Retention Policy
4. Set Pre-Production Deployments to the shortest available duration
5. Save

After the retention period expires, Vercel's cleanup job processes deletions asynchronously, typically within hours to days. To avoid waiting for retention entirely, you can delete deployments manually or use a GitHub Action.

For more details, see Vercel's deployment retention documentation.

Workarounds for immediate cleanup

If reducing retention isn't fast enough, you can trigger immediate cleanup by deleting deployments or branches directly.

Delete Vercel deployments

You can delete Vercel preview deployments from the Vercel dashboard, or programmatically using the Vercel CLI (vercel remove) or the Vercel API (DELETE /v13/deployments/{id}). When you delete the last deployment associated with a Git branch, Neon receives a webhook and deletes the corresponding preview branch immediately. This avoids leaving behind a broken preview deployment, since both the deployment and the database branch are removed together.

This approach is practical for cleaning up a small number of branches manually. You can also automate Vercel deployment deletion in CI by calling the Vercel API on PR close. See Vercel's Managing Deployments documentation for details on deleting deployments programmatically.

GitHub Action on PR close (recommended)

Neon's delete-branch-action deletes a Neon branch by name. Add this workflow to your repository to clean up the preview branch as soon as a PR is closed or merged:

name: Cleanup Neon preview branch
on:
  pull_request:
    types: [closed]
jobs:
  delete-branch:
    runs-on: ubuntu-latest
    steps:
      - uses: neondatabase/delete-branch-action@v3
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          branch: preview/${{ github.head_ref }}
          api_key: ${{ secrets.NEON_API_KEY }}

The Vercel integration creates Neon branches using the naming pattern preview/<git-branch>, so this action targets the same branches the integration creates. This works for both integration types.

This workflow requires a NEON_PROJECT_ID repository variable and a NEON_API_KEY repository secret. Find your project ID on the Project Settings page in the Neon Console, and create an API key under Account Settings > API Keys.

This action is safe to use alongside automatic cleanup. If the action deletes the branch first, the cleanup webhook that eventually fires from Vercel will find the branch already gone and handle it gracefully.

For more GitHub Actions branching workflows, see Automate branching with GitHub Actions.

Neon CLI or API

You can also delete branches programmatically using the Neon CLI or the Neon API. This is useful for building custom automation or scheduled cleanup scripts.

Branch expiration

Branch expiration lets you set a time-to-live on branches so they're automatically deleted after a fixed duration. The Vercel-Managed integration doesn't set expiration on preview branches automatically. To use this approach, you'd need a separate automation step (for example, a GitHub Action triggered on push) that sets expires_at on newly created preview branches via the Neon API. See Branch expiration for details and setup instructions.

Cleaning up existing stale branches

If you already have accumulated preview branches, start by listing what you have:

neon branches list --project-id <project-id>

This shows all branches with their names, states, and creation dates. Look for branches with the preview/ prefix that correspond to merged or deleted Git branches.

To remove stale branches:

• Neon Console: Go to the Branches page and delete branches individually
• Neon CLI: Use neon branches delete <branch-id-or-name> to remove specific branches. See CLI branches reference.
• Neon API: Use DELETE /projects/{project_id}/branches/{branch_id}. See Delete a branch with the API.

Cost impact of stale branches

Preview branches that aren't cleaned up still consume resources and count toward your plan limits. Branches inactive for 24 hours and older than 14 days are automatically archived to lower-cost storage, which reduces storage costs but doesn't eliminate them. Archived branches still count toward your plan's branch limits. If you exceed the branch limit included in your plan, the extra branches are billed at the rate shown on the Extra usage page.

FAQ

Why aren't my preview branches being deleted?

The most common cause is Vercel's deployment retention policy. With the default 6-month retention, preview branches can persist for months after a PR is closed. To fix this:

1. Reduce your Vercel retention policy for pre-production deployments
2. Set up a GitHub Action to delete branches immediately on PR close

I reduced retention but branches are still not being deleted

Vercel keeps a minimum number of recent deployments regardless of your retention settings. The project's deploymentsToKeep value (typically 10, visible via the Vercel project API) controls how many are protected. Neon branches tied to these deployments won't be auto-deleted. Use the GitHub Action workaround or manual cleanup for these branches.

Which integration type gives faster cleanup?

It depends on your deployment cadence.

The Neon-Managed Integration deletes branches based on Git branch deletion rather than Vercel's deployment retention policy, so it avoids the months-long delays described on this page. But cleanup only runs when the next preview deployment is created. At that point, Neon checks for deleted Git branches and removes the corresponding Neon branches. If no new preview deployments happen, stale branches accumulate until activity resumes.

The Vercel-Managed Integration has predictable but slow cleanup tied to deployment retention. The Neon-Managed Integration has fast cleanup during active development but no cleanup during idle periods. Both benefit from the GitHub Action approach, which works regardless of integration type and removes branches immediately on PR close.

How do I clean up branches that already accumulated?

See Cleaning up existing stale branches above for options including the Neon Console, CLI, and API.