Neon provides a set of GitHub Actions to automate the creation, deletion, and management of database branches in your Neon projects. These actions allow you to automate database branching as part of your CI/CD workflows, enabling you to create ephemeral database branches for pull requests, run tests against isolated data, and clean up resources automatically.
This guide covers how to set up and use the Neon GitHub Actions for managing database branches, including creating, deleting, resetting branches, and comparing schemas.
Getting started
To use Neon's GitHub Actions, you need to add your Neon API key and Project ID to your GitHub repository. This allows the actions to authenticate with your Neon project and perform operations on your database branches.
Automatically set up with the Neon GitHub integration
The easiest way to get started is with the Neon GitHub integration. It connects your Neon project to a GitHub repository, automatically creating the necessary NEON_API_KEY
secret and NEON_PROJECT_ID
variable for you. If you use the integration, you can skip the manual setup steps below.
Manually set up your repository
- Create a Neon API key. For instructions, see Create an API key.
- Add the key to GitHub. In your GitHub repository, navigate to Settings > Secrets and variables > Actions.
- Click New repository secret.
- Name the secret
NEON_API_KEY
and paste your API key into the value field. - Click Add secret.
- You will also need your Neon Project ID, which you can find in the Settings page of the Neon console.
- Add the Project ID to your GitHub repository as a variable:
- In your GitHub repository, navigate to Settings > Secrets and variables > Actions.
- Select Variables and click New repository variable.
- Name the variable
NEON_PROJECT_ID
and set its value to your Neon Project ID. - Click Add variable.
You can now use the Neon GitHub Actions in your workflows by referencing them in your .github/workflows
YAML files.
Available actions
Neon provides the following GitHub Actions for working with Neon branches. For detailed information on usage, inputs, and outputs, please refer to the official documentation for each action on the GitHub Marketplace.
- Create branch action: Creates a new database branch in your Neon project. This is ideal for setting up isolated environments for preview deployments or running tests against a feature branch.
- Delete branch action: Deletes a specified database branch. Use this to automate the cleanup of ephemeral branches after a pull request is merged or closed.
- Reset branch action: Resets a branch to the latest state of its parent. This is useful for refreshing a development or staging branch with the most up-to-date data.
- Schema diff action: Compares the schemas of two branches and posts a diff summary as a comment on a pull request, allowing for easy review of schema changes.
For detailed information on how to use these actions, including required inputs, outputs, and examples, check the individual actions documentation on GitHub Marketplace:
Create branch action
Creates a new database branch. Ideal for setting up isolated environments for preview deployments or feature testing.
Delete branch action
Deletes a specified database branch. Use this to clean up ephemeral branches after a pull request is merged or closed.
Reset branch action
Resets a branch to the latest state of its parent. Useful for refreshing a development branch with production data.
Schema diff action
Compares the schema of two branches and posts a diff summary as a comment on a pull request.
Example applications
For complete, deployable examples, explore these starter repositories:
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
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.