Automate branching with GitHub Actions
Create and delete branches with GitHub Actions
Neon provides the following GitHub Actions for working with Neon branches, which you can add to your CI workflows:
Create branch action
This GitHub Action creates a new branch in your Neon project.
info
The source code for this action is available on GitHub.
Prerequisites
- Using the action requires a Neon API key. For information about obtaining an API key, see Create an API key.
- Add your Neon API key to your GitHub Secrets:
- In your GitHub repository, go to Project settings and locate Secrets at the bottom of the left sidebar.
- Click Actions > New Repository Secret.
- Name the secret
NEON_API_KEY
and paste your API key in the Secret field - Click Add Secret.
Example
The following example creates a branch based on the specified parent branch:
name: Create Neon Branch with GitHub Actions Demo
run-name: Create a Neon Branch 🚀
jobs:
Create-Neon-Branch:
uses: neondatabase/create-branch-action@v5
with:
project_id: rapid-haze-373089
# optional (defaults to your project's default branch)
parent: dev
# optional (defaults to neondb)
database: my-database
branch_name: from_action_reusable
username: db_user_for_url
api_key: ${{ secrets.NEON_API_KEY }}
id: create-branch
- run: echo db_url ${{ steps.create-branch.outputs.db_url }}
- run: echo host ${{ steps.create-branch.outputs.host }}
- run: echo branch_id ${{ steps.create-branch.outputs.branch_id }}
Input variables
inputs:
project_id:
required: true
description: 'The project id'
branch_name:
required: false
description: 'The branch name'
api_key:
description: 'The Neon API key'
required: true
username:
description: 'The db role name'
required: true
database:
description: 'The database name'
default: neondb
prisma:
description: 'Use prisma or not'
default: 'false'
parent:
description: 'The parent branch name or id or LSN or timestamp. By default the default branch is used'
suspend_timeout:
description: >
Duration of inactivity in seconds after which the compute is
For more information, see [Auto-suspend configuration](https://neon.tech/docs/manage/endpoints#auto-suspend-configuration).
default: '0'
ssl:
description: >
Add sslmode to the connection string. Supported values are: "require", "verify-ca", "verify-full", "omit".
default: 'require'
Outputs
outputs:
db_url:
description: 'New branch DATABASE_URL'
value: ${{ steps.create-branch.outputs.db_url }}
db_url_with_pooler:
description: 'New branch DATABASE_URL with pooling enabled'
value: ${{ steps.create-branch.outputs.db_url_with_pooler }}
host:
description: 'New branch host'
value: ${{ steps.create-branch.outputs.host }}
host_with_pooler:
description: 'New branch host with pooling enabled'
value: ${{ steps.create-branch.outputs.host_with_pooler }}
branch_id:
description: 'New branch id'
value: ${{ steps.create-branch.outputs.branch_id }}
password:
description: 'Password for connecting to the new branch database with the input username'
value: ${{ steps.create-branch.outputs.password }}
Delete branch action
This GitHub Action deletes a branch from your Neon project.
info
The source code for this action is available on GitHub.
Prerequisites
- Using the action requires a Neon API key. For information about obtaining an API key, see Create an API key.
- Add your Neon API key to your GitHub Secrets:
- In your GitHub repository, go to Project settings and locate Secrets at the bottom of the left sidebar.
- Click Actions > New Repository Secret.
- Name the secret
NEON_API_KEY
and paste your API key in the Secret field - Click Add Secret.
Example
The following example deletes a branch with the br-long-forest-224191
branch ID from a Neon project with the project ID rapid-haze-373089
when a pull request is merged.
name: Delete Neon Branch with GitHub Actions Demo
run-name: Delete a Neon Branch 🚀
on: [push]
jobs:
delete-neon-branch:
uses: neondatabase/delete-branch-action@v3
with:
project_id: rapid-haze-373089
branch: br-long-forest-224191
api_key: { { secrets.NEON_API_KEY } }
Input variables
inputs:
project_id:
required: true
description: 'The Neon project id'
branch_id:
description: 'The Neon branch id'
deprecationMessage: 'The `branch_id` input is deprecated in favor of `branch`'
api_key:
description: 'The Neon API key, read more at https://neon.tech/docs/manage/api-keys'
required: true
branch:
description: 'The Neon branch name or id'
Outputs
This Action has no outputs.
Reset from parent action
This GitHub Action resets a child branch with the latest data from its parent branch.
Info The source code for this action is available on GitHub.
Prerequisites
- Using this action requires a Neon API key. For information about obtaining an API key, see Create an API key.
- Add your Neon API key to your GitHub Secrets:
- In your GitHub repository, go to Project settings and locate Secrets at the bottom of the left sidebar.
- Click Actions > New Repository Secret.
- Name the secret
NEON_API_KEY
and paste your API key in the Secret field. - Click Add Secret.
Example
The following example demonstrates how to reset a branch in your Neon project:
name: Reset Neon Branch with GitHub Actions Demo
run-name: Reset a Neon Branch 🚀
jobs:
Reset-Neon-Branch:
uses: neondatabase/reset-branch-action@v1
with:
project_id: rapid-haze-373089
parent: true
branch: child_branch
api_key: {{ secrets.NEON_API_KEY }}
id: reset-branch
- run: echo branch_id ${{ steps.reset-branch.outputs.branch_id }}
Input variables
inputs:
project_id:
required: true
description: 'The project id'
branch:
required: true
description: 'The branch name or id to reset'
api_key:
description: 'The Neon API key'
required: true
parent:
description: 'If specified, the branch will be reset to the parent branch'
required: false
Outputs
outputs:
branch_id:
description: 'Reset branch id'
value: ${{ steps.reset-branch.outputs.branch_id }}
Example applications
The following example applications use GitHub Actions workflows to create and delete branches in Neon.
Preview branches with Vercel
Demonstrates using GitHub Actions workflows to create a Neon branch for every Vercel preview deployment
Preview branches with Fly.io
Demonstrates using GitHub Actions workflows to create a Neon branch for every Fly.io preview deployment
Neon Twitter app
Demonstrates using GitHub Actions workflows to create a Neon branch for schema validation and perform migrations
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more detail, see Getting Support.
Last updated on