Neon Branching in GitHub Actions

These actions allow you to easily manage Neon branches within your GitHub Actions workflows. Usage is as simple as:

name: CI
on: push
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/create-branch@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

name: Cleanup
on: delete
jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/delete-branches@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

Setup

• Get your Neon API key and add it to your repository as a secret
  • Instructions on creating a Neon API key
  • Instructions on adding repository secrets
• Get your Neon project ID and add it to your repository as a variable
  • Go to your projects and click on the project you want to set up
  • The project ID will be in the URL, or you can go to the Settings tab and copy it from there
  • Instructions on adding repository variables

How It Works

This project provides two actions:

create-branch:

This action creates a Neon branch for the current GitHub branch and commit. The Neon branch name will be the GitHub branch name plus the first seven characters of the commit SHA. For example, if you create a GitHub branch called feat/my-feature and push three commits, the following Neon branches will be created:

• feat/my-feature-61b5d0a
• feat/my-feature-ff2a8ea
• feat/my-feature-389823a

The Neon branch that is created always branches off of your primary Neon branch.

delete-branches :

This action deletes all Neon branches associated with the deleted GitHub branch. From the example above, when you delete the feat/my-feature branch either directly or by merging its pull request (and have your repository set up to automatically delete branches when pull requests are merged), then the three Neon branches will be deleted.

Supported Events

The supported events are:

• push
• pull_request
• delete

The branch name is determined automatically from the event. For push and pull_request events, the branch name is the name of the branch that was pushed or the name of the branch that the pull request is for. For delete events, the branch name is the name of the branch that was deleted.

Note that you can use any combination of these events to create and delete Neon branches:

• Create branches on push
• Delete branches on delete

name: CI
on: push
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/create-branch@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

name: Cleanup
on: delete
jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/delete-branches@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

• Create branches on pull_request
• Delete branches on pull_request (set types to [closed])

name: CI
on: pull_request
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/create-branch@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

name: Cleanup
on:
  pull_request:
    types:
      - closed
jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/delete-branches@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

• Create branches on pull_request
• Delete branches on delete

name: CI
on: pull_request
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/create-branch@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

name: Cleanup
on: delete
jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/delete-branches@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

create-branch

Inputs

Name	Description	Required	Default
api-key	Your Neon API key	Yes	N/A
project-id	The ID of the Neon project to create branches in	Yes	N/A
endpoint-type	The compute endpoint type	No	read_write
endpoint-autoscaling-limit-min-cu	The minimum compute units	No	0.25
endpoint-autoscaling-limit-max-cu	The maximum compute units	No	0.25
endpoint-suspend-timeout-seconds	The auto-suspend timeout in seconds	No	0

Outputs

The create-branch action outputs two hostnames of the created branch:

direct-host

This hostname should be used for direct connections. Likely the only use for this host is for running migrations, as Prisma, for example, requires a direct connection to run migrations.

pooled-host

This hostname should be used for pooled connections. This is the hostname that should be used for all other connections, like for running smoketests or for connecting from a web application.

---

Below is an example of how you might want to use these output variables in later steps of your workflow:

name: CI

on: push

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup node
        uses: actions/setup-node@v3

      - name: Install dependencies
        run: npm ci

      - name: Create neon branch
        id: neon
        uses: autoblocksai/neon-actions/create-branch@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

      - name: Run prisma migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: postgres://${{ secrets.PG_USERNAME }}:${{ secrets.PG_PASSWORD }}@${{ steps.neon.outputs.direct-host }}:5432/neondb

      - name: Run smoke tests
        run: npm run test:smoke
        env:
          DATABASE_URL: postgres://${{ secrets.PG_USERNAME }}:${{ secrets.PG_PASSWORD }}@${{ steps.neon.outputs.pooled-host }}:5432/neondb

delete-branches

This action is meant to be used in a workflow that runs on the delete event. It will delete all Neon branches associated with the deleted GitHub branch.

Inputs

Name	Description	Required	Default
api-key	Your Neon API key	Yes	N/A
project-id	The ID of the Neon project to delete branches in	Yes	N/A

name: Cleanup

on: delete

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/delete-branches@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

More Examples

Running on pull requests

In some cases you might want to only start creating Neon branches once a pull request has been opened. The create-branch action also supports the pull_request event:

create-branch:

name: CI

on: pull_request

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/create-branch@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

For cleanup you have a few options. You can use the same workflow as the examples above to clean up the Neon branches when the pull request's branch is deleted, or you can run the cleanup when the pull request is closed. This might be preferable if your repository isn't set up to automatically delete branches when pull requests are merged.

delete-branches:

name: Cleanup

on:
  pull_request:
    types:
      - closed

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/delete-branches@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

You could also handle both to cover all your bases:

name: Cleanup

on:
  delete:
  pull_request:
    types:
      - closed

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/delete-branches@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

Only run when a migrations folder has been modified

If you keep all of your migrations in a folder and only want to run the create-branch action when that folder has been modified, you have a few options depending on your workflow setup.

If your worfklow isn't a required status check, you can likely just use the paths filter. This means it will only run when the given paths have been modified in the commit.

name: Test Migrations

on:
  push:
    paths:
      - path/to/migrations/**

jobs:
  test-migrations:
    runs-on: ubuntu-latest
    steps:
      - uses: autoblocksai/neon-actions/create-branch@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

      # Run migrations etc

This doesn't work, however, if the workflow you want to add Neon branching to contains required status checks. This is because it will only run if the pull request modifies the files in the paths filter.

From the GitHub docs:

If a workflow is skipped due to branch filtering, path filtering, or a commit message, then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.

In this case you probably want to use something like dorny/paths-filter, which will allow you to gather the changed files in a step and then use those results to determine which subsequent steps to run. Unfortunately, though, you will need to add an if statement to each step involving Neon:

name: CI

on: push

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup node
        uses: actions/setup-node@v3

      - name: Install dependencies
        run: npm ci

      - uses: dorny/paths-filter@v2
        id: changes
        with:
          filters: |
            migrations:
              - 'path/to/migrations/**'

      - if: steps.changes.outputs.migrations == 'true'
        name: Create neon branch
        id: neon
        uses: autoblocksai/neon-actions/create-branch@v1
        with:
          api-key: ${{ secrets.NEON_API_KEY }}
          project-id: ${{ vars.NEON_PROJECT_ID }}

      - if: steps.changes.outputs.migrations == 'true'
        name: Run prisma migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: postgres://${{ secrets.PG_USERNAME }}:${{ secrets.PG_PASSWORD }}@${{ steps.neon.outputs.direct-host }}:5432/neondb

      - if: steps.changes.outputs.migrations == 'true'
        name: Run smoke tests
        run: npm run test:smoke
        env:
          DATABASE_URL: postgres://${{ secrets.PG_USERNAME }}:${{ secrets.PG_PASSWORD }}@${{ steps.neon.outputs.pooled-host }}:5432/neondb