Neon Serverless Postgres Ephemeral Branch FinOps Pruner

id: neon-preview-branch-finops-pruner
namespace: company.finops

description: |
  Audits and prunes stale ephemeral database branches in Neon serverless Postgres.
  Detects idle preview branches created during CI/CD workflows, enforces deletion
  ceilings, protects default branches, and alerts Slack with reclaimed quota metrics.

inputs:
  - id: neon_project_id
    type: STRING
    defaults: "proud-violet-987654"
    description: Neon project identifier containing ephemeral preview branches.

  - id: preview_prefix
    type: STRING
    defaults: "preview/"
    description: Branch name prefix identifying ephemeral CI/CD preview branches.

  - id: retention_hours
    type: INT
    defaults: 48
    description: Inactivity age threshold in hours beyond which preview branches are
      considered stale.

  - id: max_prune_count
    type: INT
    defaults: 5
    description: Maximum number of branches to delete in a single execution to
      prevent unintended bulk eviction.

  - id: dry_run
    type: BOOL
    defaults: true
    description: When true, audits stale branches and plans eviction without
      dispatching DELETE calls.

tasks:
  - id: fetch_branches
    type: io.kestra.plugin.core.http.Request
    description: Retrieves all active and idle database branches from the Neon REST API
    uri: "https://console.neon.tech/api/v2/projects/{{ inputs.neon_project_id
      }}/branches"
    method: GET
    contentType: application/json
    headers:
      Accept: application/json
      Authorization: "Bearer {{ secret('NEON_API_KEY') }}"

  - id: filter_stale_branches
    type: io.kestra.plugin.core.output.OutputValues
    description: Filters idle preview branches exceeding retention period while
      protecting primary branches
    values:
      total_branches: "{{ outputs.fetch_branches.body | jq('.branches | length') | first }}"
      stale_branches: >-
        {{
          outputs.fetch_branches.body | jq('[.branches[] | select((.default == false) and ((.protected // false) == false) and (.name | startswith(\"' ~ inputs.preview_prefix ~ '\")) and .updated_at < \"' ~ (now() | dateAdd(-inputs.retention_hours, 'HOURS') | date("yyyy-MM-dd'T'HH:mm:ss'Z'", timeZone='UTC')) ~ '\")] | .[0:' ~ inputs.max_prune_count ~ ']') | first
        }}

  - id: evaluate_stale_branches
    type: io.kestra.plugin.core.flow.If
    description: Checks whether any stale preview branches matched the retention filter
    condition: "{{ (outputs.filter_stale_branches.values.stale_branches | length) > 0 }}"
    then:
      - id: evaluate_dry_run_gate
        type: io.kestra.plugin.core.flow.If
        description: Evaluates whether to simulate deletions or execute actual REST API
          deletions
        condition: "{{ inputs.dry_run }}"
        then:
          - id: log_simulation_plan
            type: io.kestra.plugin.core.log.Log
            description: Logs planned branch deletions without making destructive mutations
            message: "DRY RUN: Found {{ outputs.filter_stale_branches.values.stale_branches
              | length }} stale preview branch(es) ready for deletion out of {{
              outputs.filter_stale_branches.values.total_branches }} total
              branches in project {{ inputs.neon_project_id }}."

        else:
          - id: prune_branches
            type: io.kestra.plugin.core.flow.Loop
            description: Sequentially deletes identified stale preview branches from Neon
              project
            values: "{{ outputs.filter_stale_branches.values.stale_branches }}"
            concurrencyLimit: 1
            tasks:
              - id: delete_branch
                type: io.kestra.plugin.core.http.Request
                description: Dispatches DELETE request to Neon API for stale preview branch
                uri: "https://console.neon.tech/api/v2/projects/{{ inputs.neon_project_id
                  }}/branches/{{ item.value.id }}"
                method: DELETE
                headers:
                  Accept: application/json
                  Authorization: "Bearer {{ secret('NEON_API_KEY') }}"

              - id: log_prune_action
                type: io.kestra.plugin.core.log.Log
                description: Records deleted branch identifier and name
                message: "Deleted stale preview branch '{{ item.value.name }}' (ID: {{
                  item.value.id }})."

          - id: verify_readback
            type: io.kestra.plugin.core.http.Request
            description: Queries Neon API to verify deleted branches are evicted
            uri: "https://console.neon.tech/api/v2/projects/{{ inputs.neon_project_id
              }}/branches"
            method: GET
            headers:
              Accept: application/json
              Authorization: "Bearer {{ secret('NEON_API_KEY') }}"

          - id: log_readback_verification
            type: io.kestra.plugin.core.log.Log
            description: Confirms total active branches remaining after deletion
            message: "Readback verified: Neon project {{ inputs.neon_project_id }} now has
              {{ outputs.verify_readback.body | jq('.branches | length') | first
              }} active branch(es)."

      - id: notify_slack_summary
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Sends summary card to Slack with branch reclamation metrics
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        messageText: |
          :wastebasket: *Neon Ephemeral Branch FinOps Pruner Report*
          *Project ID:* `{{ inputs.neon_project_id }}`
          *Mode:* `{{ inputs.dry_run ? 'DRY RUN (Simulated)' : 'PRODUCTION (Executed)' }}`
          *Stale Branches Evaluated:* `{{ outputs.filter_stale_branches.values.stale_branches | length }}`
          *Total Project Branches:* `{{ outputs.filter_stale_branches.values.total_branches }}`
          *Retention Age:* `>{{ inputs.retention_hours }} hours`
          *Preview Prefix:* `{{ inputs.preview_prefix }}`

    else:
      - id: log_healthy_state
        type: io.kestra.plugin.core.log.Log
        description: Logs confirmation when no stale branches exceed retention threshold
        message: "Neon project {{ inputs.neon_project_id }} has {{
          outputs.filter_stale_branches.values.total_branches }} active
          branch(es). Zero stale preview branches exceed the {{
          inputs.retention_hours }}-hour threshold."

triggers:
  - id: daily_maintenance_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: Daily scheduled sweep of stale preview branches. Shipped disabled
      by default.
    cron: "0 2 * * *"
    disabled: true

  - id: pr_closed_webhook
    type: io.kestra.plugin.core.trigger.Webhook
    description: Event-driven webhook trigger to run cleanup after CI/CD pull request merges
    key: "{{ secret('WEBHOOK_KEY') }}"

errors:
  - id: alert_on_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alerts on-call Slack channel if branch pruning encounters an error
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    messageText: |
      :warning: *Neon Ephemeral Branch Pruner FAILED on execution {{ execution.id }}*
      *Project:* `{{ inputs.neon_project_id }}`
      Please verify Neon API key permissions and rate limit status.

Modern engineering teams running serverless PostgreSQL on Neon spin up isolated database branches for preview environments on every pull request. However, when pull requests merge or close without deleting their database branch, preview environments linger indefinitely. Over time, projects exhaust their account branch quota (preventing new CI preview builds) and accumulate ongoing storage costs for abandoned data copies.

This blueprint provides an automated FinOps guard that queries the Neon Cloud Management REST API, discovers idle preview branches older than a configurable retention threshold, enforces a safe deletion ceiling, and cleans up stale branches with dry-run protection and double-check readback verification.

How it works

fetch_branches (io.kestra.plugin.core.http.Request) queries the Neon REST API for all branches in the target project.
filter_stale_branches (io.kestra.plugin.core.output.OutputValues) evaluates branches using Pebble date math and jq filtering. It isolates branches matching inputs.preview_prefix, strictly excludes default and protected branches, and identifies those whose updated_at timestamp exceeds inputs.retention_hours.
evaluate_stale_branches (io.kestra.plugin.core.flow.If) checks whether any stale branches require action.
evaluate_dry_run_gate (io.kestra.plugin.core.flow.If) branches execution based on inputs.dry_run:
- When dry_run: true, it logs the planned deletion list without mutating cloud resources.
- When dry_run: false, prune_branches (io.kestra.plugin.core.flow.Loop) iterates sequentially over each branch with concurrencyLimit: 1 to dispatch DELETE requests to the Neon API.
verify_readback (io.kestra.plugin.core.http.Request) performs an immediate post-deletion readback to verify that target branches are no longer present.
notify_slack_summary (io.kestra.plugin.slack.notifications.SlackIncomingWebhook) dispatches an operational summary card to Slack detailing the reclaimed branches and current project branch count.

What you get

Automated preview branch hygiene preventing CI build failures caused by Neon branch quota limits.
Safe-by-default execution with dry_run: true and protection for default and protected branches.
Bounded blast radius through max_prune_count, capping how many branches can be deleted per execution.
Readback verification confirming cloud state before reporting success.
Native declarative orchestration requiring zero external container runners or custom Python scripts.

Who it's for

Platform Engineers and DevOps teams managing Neon serverless Postgres in CI/CD pipelines.
FinOps practitioners tracking and reducing non-production cloud database storage waste.
Database Administrators overseeing ephemeral preview environments for engineering teams.

Why orchestrate this with Kestra

Custom bash scripts and cron jobs querying cloud APIs often lack execution history, credential governance, and error handling. Running branch cleanup through Kestra provides unified secrets management for NEON_API_KEY, visual execution auditing, automated retries, and both scheduled and event-driven webhook execution directly linked to Slack notifications.

Pitfalls

Parent Branch Dependencies: Deleting a branch with child branches could fail if child dependencies exist. This blueprint targets leaf preview branches by filtering for the configured preview prefix (e.g., preview/).
Active Compute Endpoints: Neon automatically tears down ephemeral compute endpoints associated with a branch when the branch is deleted, but ensure long-running queries on preview environments are not abruptly disconnected by configuring a sufficient retention_hours buffer.
API Rate Limits: Neon management API endpoints enforce rate limits. The blueprint enforces concurrencyLimit: 1 on the deletion loop to avoid throttling during batch cleanups.

Prerequisites

A Neon serverless Postgres account and project.
A Neon Cloud API Key with project admin permissions.
A Slack incoming webhook endpoint for notifications.

Secrets

NEON_API_KEY: Neon API Key generated from the Neon Console account settings.
SLACK_WEBHOOK_URL: Slack Incoming Webhook URL for alerting.
WEBHOOK_KEY: Secret authentication key for the event-driven webhook trigger.

Quick start

Store NEON_API_KEY, SLACK_WEBHOOK_URL, and WEBHOOK_KEY in your Kestra namespace secrets.
Deploy this flow and run a manual execution with dry_run: true to review stale preview branches without deleting them.
Once verified, set dry_run: false to enable active branch cleanup.
Enable the daily_maintenance_schedule trigger for continuous automated pruning, or call pr_closed_webhook from your GitHub Actions workflow when a pull request closes.

How to extend

GitHub Pull Request Integration: Pass the pull request branch name directly to inputs.preview_prefix from a GitHub Actions webhook to trigger immediate branch deletion as soon as a pull request merges.
Threshold Alerting: Add an escalation step using core.execution.Fail if project branch usage exceeds 90% of your plan's branch limit.
Multi-Project Sweeps: Wrap this workflow in a parent flow using io.kestra.plugin.core.flow.Subflow to sweep multiple Neon projects across development and staging environments.

Prune Stale Ephemeral Preview Branches in Neon Serverless Postgres

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Pitfalls

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

Prune Stale Ephemeral Preview Branches in Neon Serverless Postgres

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Pitfalls

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Cloud Blueprints

Gate Deployments on npm Audit Counts

Multi-cloud deployment pipeline with Docker, ngrok, GCP Cloud Run, and Azure Container Apps

Prune noncurrent object versions billed forever behind a versioned bucket

Gate OIDC Signing-Key Rollovers with a Pinned JWKS

Memcached Slab Eviction Sentinel

New Relic APM Apdex Score Degradation Sentinel

More Data Blueprints

Find Documentation Gaps with a Meilisearch Zero-Result Queries Review

Meilisearch Index Rebuild Pipeline with Dated Indexes and Manual Swap

Meilisearch Index Health Sentinel and Search Audit

Weekly Meilisearch Facet Report on Documentation Sections

Meilisearch Indexing Queue Staleness Sentinel

Ingest a Documentation Site into Meilisearch with Python Shaping

New to Kestra?