The Neon GitHub integration
Connect Neon Postgres to a GitHub repository and build GitHub Actions workflows
The Neon GitHub integration connects your Neon projects to corresponding GitHub repositories, helping you incorporate your database into your developer workflow. For example, create a database branch for each pull request using GitHub Actions. We’ll provide you with a sample GitHub Actions workflow to help you get started.
How it works
The integration installs the GitHub App, letting you select which repositories you want to make accessible to Neon. When you connect a particular project to an available repository in GitHub, the integration uses the GitHub App to set a Neon API key secret and a Neon project ID variable in the selected repository. Your project is now connected, and you can use GitHub Actions to include this project’s database in your workflow.
The sample workflow is intended as a basic template you can expand on or customize to build your own workflows.
This guide walks you through the following steps:
- Installing the GitHub App
- Connecting a Neon project to a GitHub repository
- Adding the sample GitHub Actions workflow to your repository
Prerequisites
The steps described below assume the following:
- You have a Neon account and project. If not, see Sign up for a Neon account.
- You have a GitHub account and a repository that you want to connect to your Neon project.
Install the GitHub App and connect your Neon project
To get started:
-
In the Neon Console, navigate to the Integrations page in your Neon project.
-
Locate the GitHub card and click Add.
-
On the GitHub drawer, click Install GitHub App.
-
If you have more than one GitHub account, select the account where you want to install the GitHub app.
-
Select whether to install and authorize the GitHub app for All repositories in your GitHub account or Only select repositories.
- Selecting All repositories authorizes the app on all repositories in your GitHub account, meaning that you can to connect your Neon project to any of them.
- Selecting Only select repositories authorizes the app on one or more repositories, meaning that you can only connect your Neon project to the selected repositories (you can authorize additional repositories later if you need to).
-
If you authorized the app on All repositories or multiple repositories, select a GitHub repository to connect to the current Neon project, and click Connect. If you authorized the GitHub app on a single GitHub repository, you have already completed this step.
You are directed to the Actions tab on the final page of the setup, where a sample GitHub Actions workflow is provided. You can copy this workflow to your GitHub repository to establish a basic database branching process. For instructions, see Add the GitHub Actions workflow to your repository.
Add the GitHub Actions workflow to your repository
The sample GitHub Actions workflow includes:
- A
Create Neon Branch
action that creates a new Neon branch in your Neon project when you open or reopen a pull request in the connected GitHub repository. - Code that you can uncomment to add a database migration command to your workflow.
- A
Delete Neon Branch
action that deletes the Neon branch from your Neon project when you close the pull request.
To add the workflow to your repository:
-
In your repository, create a workflow file in the
.github/workflows
directory; for example, create a file namedneon_workflow.yml
.- If the
.github/workflows
directory already exists, add the file. - If your repository doesn't have a
.github/workflows
directory, add the file.github/workflows/neon-workflow.yml
. This creates the.github
andworkflows
directories and theneon-workflow.yml
file.
If you need more help with this step, see Creating your first workflow, in the GitHub documentation.
note
For GitHub to discover GitHub Actions workflows, you must save the workflow files in a directory called
.github/workflows
in your repository. You can name the workflow file whatever you like, but you must use.yml
or.yaml
as the file name extension. - If the
-
Copy the workflow code into your
neon-workflow.yml
file. -
Commit your changes.
Using the GitHub Actions workflow
To use the sample workflow, create a pull request in your GitHub application repository. This will trigger the Create Neon Branch
action. You can verify that a branch was created on the Branches page in the Neon Console. You should see a new branch with a preview/pr-
name prefix.
Closing the pull request removes the Neon branch from the Neon project, which you can also verify on the Branches page in the Neon Console.
To view workflow results in GitHub, follow the instructions in Viewing your workflow results, in the GitHub documentation.
Building your own GitHub Actions workflow
The sample workflow provided by the GitHub integration serves as a template, which you can expand on or customize. The workflow uses Neon's create and delete branch GitHub Actions, which you can find here:
Neon also offers a Reset a Neon Branch action that allows you to reset a database branch to match the current state of its parent branch. This action is useful in a feature-development workflow, where you may need to reset a development branch to the current state of your production branch before beginning work on a new feature.
To incorporate the reset action into your workflow, you can use code like this, tailored to your specific requirements:
The possibilities are endless. You can integrate Neon's GitHub Actions into your workflow, develop custom actions, or combine Neon's actions with those from other platforms or services.
If you're new to GitHub Actions and workflows, GitHub's Quickstart for GitHub Actions is a good place to start.
Example applications with GitHub Actions workflows
The following example applications utilize GitHub Actions workflows to create and delete branches in Neon. These examples can serve as references when building your own workflows.
note
The Neon GitHub integration configures a NEON_API_KEY
secret and a PROJECT_ID
variable in your GitHub repository. Depending on the specific example application, additional or different variables and secrets may have been used. As you develop your workflows, you might also need to incorporate various other variables and secrets.
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
Connect more Neon projects with the GitHub App
If you've installed the GitHub app previously, it's available to use with any project in your Neon account.
To connect another Neon project to a GitHub repository:
- In the Neon Console, navigate to the Integrations page in your Neon project.
- Locate the GitHub integration and click Add.
- Select a GitHub repository to connect to your Neon project, and click Connect.
note
Connecting to the same GitHub repository from different Neon projects is not supported.
Secret and variable set by the GitHub integration
When connecting a Neon project to a GitHub repository, the GitHub integration performs the following actions:
- Generates a Neon API key for your Neon account
- Creates a
NEON_API_KEY
secret in your GitHub repository - Adds a
NEON_PROJECT_ID
variable to your GitHub repository
The NEON_API_KEY
allows you to run any Neon API method or Neon CLI command, which means you can develop actions and workflows that create, update, and delete various objects in Neon such as projects, branches, databases, roles, and computes.
The NEON_PROJECT_ID
variable defines the Neon project that is connected to the repository. Operations run on Neon via the Neon API or CLI typically require specifying the Neon project ID, as a Neon account may have more than one Neon project.
The sample GitHub Actions workflow provided by the Neon GitHub integration depends on these variables and secrets to perform actions in Neon.
note
The variables and secrets are removed if you disconnect a Neon project from the associated GitHub repository. The items are removed for all Neon projects and associated repositories if you remove the Neon GitHub integration from your Neon account. See Remove the GitHub integration.
Neon API key
To view the Neon API key created by the integration:
- In the Neon Console, click your profile at the top right corner of the page.
- Select Account settings.
- Select API keys.
The API key created by the integration should be listed with a name similar to the following: API key for GitHub (cool-darkness-12345678). You cannot view the key itself, only the name it was given, the time it was created, and when the key was last used.
Neon project ID variable and Neon API key secret
To view the variable containing your Neon project ID:
- Navigate to your GitHub account page.
- From your GitHub profile menu, select Your repositories.
- Select the repository that you chose when installing the Neon GitHub integration.
- On the repository page, select the Settings tab.
- Select Secrets and variables > Actions from the sidebar.
Your NEON_API_KEY
secret is listed on the Secrets tab, and the NEON_PROJECT_ID
variable is listed on the Variables tab.
Disconnect a Neon project from a GitHub repository
Disconnecting a Neon project from a GitHub repository performs the following actions for the Neon project:
- Removes the Neon API key created for this integration from your Neon account.
- Removes the GitHub secret containing the Neon API key from the associated GitHub repository.
- Removes the GitHub variable containing your Neon project ID from the associated GitHub repository.
Any GitHub Actions workflows you've added to the GitHub repository that are dependent on these secrets and variables will no longer work.
To disconnect your Neon project:
- In the Neon Console, navigate to the Integrations page for your project.
- Locate the GitHub integration and click Manage to open the GitHub integration drawer.
- Click Disconnect.
Remove the GitHub integration
Removing the GitHub integration performs the following actions for all Neon projects that you connected to a GitHub repository using the GitHub integration:
- Removes the Neon API keys created for Neon-GitHub integrations from your Neon account.
- Removes GitHub secrets containing the Neon API keys from the associated GitHub repositories.
- Removes the GitHub variables containing your Neon project IDs from the associated GitHub repositories.
Any GitHub Actions workflows you've added to GitHub repositories that are dependent on these secrets and variables will no longer work.
To remove the GitHub integration:
- In the Neon Console, navigate your account Profile.
- Select Account settings.
- Select Integrations.
- Click Remove.
Resources
- Creating GitHub Actions
- Quickstart for GitHub Actions
- Database Branching Workflows
- Database branching workflow guide for developers
Feedback and future improvements
If you've got feature requests or feedback about what you'd like to see from the Neon GitHub integration, let us know via the Feedback form in the Neon Console or our feedback channel on Discord.
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.