Automate branching 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
• Delete branch action
• Reset from parent action
• Schema Diff action

Create branch action

This GitHub Action creates a new branch in your Neon project.

Prerequisites

• A Neon API key. For information about obtaining an API key, see Create an API key.
• You will need to add your Neon API key to your GitHub repository secrets. See Add a Neon API key to your GitHub repository secrets for instructions.

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:  steps:  - uses: neondatabase/create-branch-action@v5  id: create-branch  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 }}  - 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 primary branch is used'  suspend_timeout:  description: >  Duration of inactivity in seconds after which the compute endpoint is  For more information, see [Scale to zero configuration](/docs/manage/computes#scale-to-zero-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.

Prerequisites

• A Neon API key. For information about obtaining an API key, see Create an API key.
• You will need to add your Neon API key to your GitHub repository secrets. See Add a Neon API key to your GitHub repository secrets for instructions.

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:  steps:  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.com/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.

Prerequisites

• A Neon API key. For information about obtaining an API key, see Create an API key.
• You will need to add your Neon API key to your GitHub repository secrets. See Add a Neon API key to your GitHub repository secrets for instructions.

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:  steps:  - uses: neondatabase/reset-branch-action@v1  id: reset-branch  with:  project_id: rapid-haze-373089  parent: true  branch: child_branch  api_key: ${{ secrets.NEON_API_KEY }}  - 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  cs_role_name:  description: 'The output connection string db role name'  required: false  cs_database:  description: 'The output connection string database name'  required: false  cs_prisma:  description: 'Use prisma in output connection string or not'  required: false  default: 'false'  cs_ssl:  description: >  Add sslmode to the connection string. Supported values are: "require", "verify-ca", "verify-full", "omit".  required: false  default: 'require'

• project_id: The ID of your Neon project. Find this value in the Neon Console on the Settings page.
• parent: If specified, the branch will be reset to the latest state of the parent branch.
• branch: The name or id of the branch to reset.
• api_key: An API key created in your Neon account.

The action outputs a connection string. You can modify the connection string with these optional connection string (cs_*) inputs:

• cs_role_name: The output connection string database role name.
• cs_database: The output connection string database name.
• cs_prisma: Use Prisma in output connection string or not. The default is 'false'.
• cs_ssl: Add sslmode to the connection string. Supported values are: "require", "verify-ca", "verify-full", "omit". The default is "require".

Outputs

outputs:  branch_id:  description: 'Reset branch id'  value: ${{ steps.reset-branch.outputs.branch_id }}  db_url:  description: 'DATABASE_URL of the branch after the reset'  value: ${{ steps.reset-branch.outputs.db_url }}  db_url_with_pooler:  description: 'DATABASE_URL with pooler of the branch after the reset'  value: ${{ steps.reset-branch.outputs.db_url_with_pooler }}  host:  description: 'Branch host after reset'  value: ${{ steps.reset-branch.outputs.host }}  host_with_pooler:  description: 'Branch host with pooling enabled after reset'  value: ${{ steps.reset-branch.outputs.host_with_pooler }}  password:  description: 'Password for connecting to the branch database after reset'  value: ${{ steps.reset-branch.outputs.password }}

• branch_id: The ID of the newly reset branch.
• db_url: Database connection string for the branch after the reset.
• db_url_with_pooler: The pooled database connection string for the branch after the reset.
• host: The branch host after the reset.
• host_with_pooler: The branch host with pooling after the reset.
• password: The password for connecting to the branch database after the reset.

Schema Diff action

This action performs a database schema diff on specified Neon branches for each pull request and writes comment to the pull request in GitHub highlighting the schema differences.

It supports workflows where schema changes are made on a branch. When you create or update a pull request containing schema changes, the action automatically generates a comment within the pull request. By including the schema diff as part of the comment, reviewers can easily assess the changes directly within the pull request.

Prerequisites

• A Neon API key. For information about obtaining an API key, see Create an API key.
• You will need to add your Neon API key to your GitHub repository secrets. See Add a Neon API key to your GitHub repository secrets for instructions.

You can easily set up the prerequisites mentioned above using our GitHub integration, which takes care of the entire process and automatically.

Example

The following example performs a schema diff on a database named mydatabase between the compare_branch and the base_branch branch.

steps:  - uses: neondatabase/schema-diff-action@v1  with:  project_id: ${{ vars.NEON_PROJECT_ID }}  compare_branch: preview/pr-${{ github.event.number }}-${{ needs.setup.outputs.branch }}  base_branch: production  api_key: ${{ secrets.NEON_API_KEY }}  database: mydatabase  username: myrole

Here's an example workflow that incorporates the action:

name: Schema Diff for Pull Requests on:  pull_request:  types:  - opened  - synchronize  - reopened  jobs:  schema_diff:  permissions:  pull-requests: write  contents: read  runs-on: ubuntu-latest  steps:  - name: Schema Diff  uses: neondatabase/schema-diff-action@v1  with:  project_id: ${{ vars.NEON_PROJECT_ID }}  compare_branch: preview/pr-${{ github.event.number }}  base_branch: production  api_key: ${{ secrets.NEON_API_KEY }}  database: mydatabase  username: myrole

In this workflow, the action is triggered by pull request events such as opened, reopened, or synchronize (when new commits are pushed to an existing PR).

The branches to compare are specified by the compare_branch and base_branch inputs.

• The compare_branch is the branch linked to the pull request — it's the "downstream" dev branch that contains your proposed schema changes, and is typically created by the Create branch action and defined by preview/pr-${{ github.event.number }} in the example above.

• The base_branch is the branch you are merging into. It's the "upstream" branch used as the reference point for the comparison. If you don’t explicitly specify the base_branch, the action defaults to comparing the compare_branch with its parent branch. The base_branch branch is usually named production, which is default name of the root branch created with each Neon project.

• The database is the name of the database containing the schema to be compared.

• The username is the name of the Postgres role that owns the database.

• permissions allows comments to be written on pull requests and repository contents to be read. These permissions are necessary if, for example, you need to check out your branch to run migrations.

  permissions:  pull-requests: write  contents: read

With the permissions above you will only allow read access to repository contents (needed to checkout the current branch, for example) and write access to pull requests.

After performing the schema diff comparison:

• The action generates an SQL patch summarizing the changes if there are schema differences between the branches.
• The action then posts a comment to the pull request containing the details of the schema diff.
• Instead of spamming the PR with multiple comments, the action updates the same comment to reflect any changes as new commits are pushed.
• If there are no schema differences between the compare_branch and the base_branch, the action doesn't add or update a comment, keeping your PR clean.

Input variables

inputs:  github-token:  description: The GitHub token used to create an authenticated client  required: false  default: ${{ github.token }}  project_id:  description: The project id  required: true  compare_branch:  description: The compare branch name or id (downstream branch)  required: true  api_key:  description: The Neon API key  required: true  base_branch:  description: The base branch name or id (upstream branch)  required: false  api_host:  description: The Neon API Host  default: https://console.neon.tech/api/v2  username:  description: The db role name  default: neondb_owner  database:  description: The database name  default: neondb  timestamp:  description: The timestamp of the downstream branch to compare against. Leave it empty  to compare against the latest changes in your compare branch  lsn:  description: The LSN of the downstream branch to compare against. Leave it empty to  compare against the latest changes in your compare branch

Outputs

diff:  description: The schema diff SQL patch comment_url:  description: The url of the comment containing the schema diff

The schema diff SQL patch is posted as a Neon Schema Diff summary comment in the pull request, similar to this example.

The comment_url allows you to easily share the schema diff for review. It also allows developers or scripts to access the comment programmatically for use in other automations.

Add a Neon API key to your GitHub repository secrets

Using Neon's GitHub Actions requires adding a Neon API key to your GitHub repository secrets. There are two ways you can perform this setup:

• Using the Neon GitHub Integration (recommended) — this integration connects your Neon project to your GitHub repository, creates an API key, and sets the API key in your GitHub repository for you. See Neon GitHub Integration for instructions.

• Manual setup — this method requires obtaining a Neon API key and configuring it manually in your GitHub repository.

  1. Obtain a Neon API key. See Create an API key for instructions.
  2. In your GitHub repository, go to Project settings and locate Secrets at the bottom of the left sidebar.
  3. Click Actions > New Repository Secret.
  4. Name the secret NEON_API_KEY and paste your API key in the Secret field
  5. Click Add Secret.

Example applications

The following example applications use GitHub Actions workflows to create and delete branches in Neon.

• Preview branches with Cloudflare Pages

  Demonstrates using GitHub Actions workflows to create a Neon branch for every Cloudflare Pages preview deployment

• 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