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

Create branch action

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

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:
  1. In your GitHub repository, go to Project settings and locate Secrets at the bottom of the left sidebar.
  2. Click Actions > New Repository Secret.
  3. Name the secret NEON_API_KEY and paste your API key in the Secret field
  4. Click Add Secret.

Example

The following example creates a branch from the main branch in your Neon project

name: Create Neon Branch with GitHub Actions Demo
run-name: Create a Neon Branch 🚀
jobs:
  Create-Neon-Branch:
    uses: neondatabase/create-branch-action@v4
    with:
      project_id: rapid-haze-373089
      parent_id: br-long-forest-224191
      branch_name: from_action_reusable
      api_key: {{ secrets.NEON_API_KEY }}
    id: create-branch
  - run: echo project_id ${{ steps.create-branch.outputs.project_id}}
  - run: echo branch_id ${{ steps.create-branch.outputs.branch_id}}

Input variables

• project_id: The ID of your Neon project. You can find this value in the Neon Console, on the Project settings page.
• parent_branch_id: The ID of the parent branch, typically the main branch of your project. You can find this value in the Neon Console. Select Branches from the sidebar, and then select the branch. A branch ID has a br- prefix.
• branch_name: This is an optional parameter. If unspecified, the branch name will default to the same value as the branch_id of the newly created branch, which is a generated value that starts with a br- prefix.
• api_key: An API key created in your Neon account. For instructions, see Create an API key.

Outputs

outputs:
  branch_id:
    description: "Newly created branch Id"
    value: ${{ steps.output-branch-id.outputs.branch_id }}
  project_id:
    description: "Project Id"
    value: ${{ steps.output-project-id.outputs.project_id }}

• branch_id: The ID of the newly created branch.
• project_id: The ID of the parent branch.

Delete branch action

This GitHub Action deletes a branch from your Neon project.

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:
  1. In your GitHub repository, go to Project settings and locate Secrets at the bottom of the left sidebar.
  2. Click Actions > New Repository Secret.
  3. Name the secret NEON_API_KEY and paste your API key in the Secret field
  4. 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

• project_id: The ID of your Neon project. You can find this value in the Neon Console, on the Project settings page.
• branch: The ID or name of the branch you want to delete. Select Branches from the sidebar, and then select the branch. A branch ID has a br- prefix.
• api_key: An API key created in your Neon account. For instructions, see Create an API key.

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:
  1. In your GitHub repository, go to Project settings and locate Secrets at the bottom of the left sidebar.
  2. Click Actions > New Repository Secret.
  3. Name the secret NEON_API_KEY and paste your API key in the Secret field.
  4. 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

• project_id: The ID of your Neon project. Find this value in the Neon Console on the Project settings page.
• parent: If specified, the branch will be reset to the latest (HEAD) of parent branch.
• branch: The name or id of the branch to reset.
• api_key: An API key created in your Neon account. See Create an API key for instructions.

Outputs

outputs:
  branch_id:
    description: "Reset branch id"
    value: ${{ steps.reset-branch.outputs.branch_id }}

• branch_id: The ID of the newly reset branch.

Example applications

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

• Neon Twitter app

  A micro-blogging application that uses GitHub Actions to create and delete a branch with each pull request

• Preview branches app

  An application demonstrating using GitHub Actions with preview deployments in Vercel