Learn how Neon compares to Aurora Serverless v2 - TL;DR: faster cold starts, responsive autoscaling, 80% lower costs
15.4kLog InSign Up
Docs/Features/Branching/Branching with GitHub Actions

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:

tip

Neon supports a GitHub integration that connects your Neon project to a GitHub repository. The integration automatically configures a NEON_API_KEY secret and PROJECT_ID variable in your GitHub repository and provides a sample GitHub Actions workflow that utilizes Neon's GitHub Actions. See Neon GitHub integration for more.

Create branch action

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

GitHub Actions Marketplace

You can find this action on the GitHub Actions Marketplace: Neon Database Create Branch Action.

Prerequisites

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/endpoints#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.

GitHub Actions Marketplace

You can find this action on the GitHub Actions Marketplace: Neon Database Delete Branch.

Prerequisites

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.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.

GitHub Actions Marketplace

You can find this action on the GitHub Actions Marketplace: Neon Database Reset Branch Action.

Prerequisites

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.

GitHub Actions Marketplace

You can find this action on the GitHub Actions Marketplace: Neon Schema Diff GitHub Action.

Prerequisites

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: main
      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: main
          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 main, 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.

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 details, see Getting Support.

PreviousBranching with the API
NextBranching — Testing queries

Last updated on

Was this page helpful?

On this page

Edit this page on GitHub