Set up a Neon PR branch for a React Native Expo application using GitHub actions

It is essential to test any changes before merging them into a main or feature branch to catch bugs before they make it to production and ensure existing functionality continues to work as expected. Testing against a copy of production data is recommended to better find data-related issues.

Previously, this process was problematic and time-consuming, often involving multiple teams. Luckily, Neon has a built-in branching mechanism, which allows you to create a copy of your data quickly.

In this tutorial, you will learn how to create a preview build for each pull request for a React Native Expo application. You will also learn how to set up a corresponding Neon database branch to be used with the preview build—and all this will be done within a single GitHub Action. Then, once the pull request is closed, you’ll learn how to clean up your resources with another GitHub Action.

Prerequisites

Before we begin, you will need to have a few things already set up.

• An Expo account for deploying and testing preview branches
• A Neon account with a database project for branching
• A GitHub repository containing your Expo application

Setting up GitHub

The first thing we need to do is add the following secrets and variables to our GitHub repository. These secrets and variables will be used throughout our GitHub Actions.

On your GitHub repository page, navigate to Settings → Secrets and variables → Actions and add the following secrets and variables.

• Neon API Key: Obtain a Neon API key from the API Keys by clicking on your avatar in the upper right corner of the Neon dashboard, then Account Settings → API Keys. Once you have created your API key, add it to your GitHub projects Repository Secrets with the name NEON_API_KEY.
  

• Neon Project ID: The Neon Project ID can be obtained from your Neon project’s Settings → General page. Add the Neon Project ID to your GitHub projects Repository Variables under the name NEON_PROJECT_ID.
  

• Neon Database Username: Add the DB Role to be used for branch creation to your GitHub projects Repository Variables under the name NEON_USERNAME.
  

• Expo Token: Obtain an Expo access token by going to Account Settings → Access tokens from the Expo dashboard. Then add a Robot user by clicking on Add robot and giving it the name GITHUB_ACTIONS. Next, click Create token and give it a descriptive, meaningful name, something like GitHub actions token for PR builds. Finally, copy the token and add it to your GitHub projects Repository Secrets with the name EXPO_TOKEN.
  

Creating a custom preview build for pull requests

With the GitHub project secrets and variables set, it’s time to configure GitHub Actions to handle pull requests made to the repository.

Create a new GitHub Actions file from your Expo project's root directory in the GitHub workflows directory.

MacOS / Linux

touch ./.github/workflows/deploy-preview.yml

Windows

mkdir "./.github/workflows" && call > ./.github/workflows/deploy-preview.yml

The following code defines the steps the GitHub Action will perform. Copy and paste this code into the file you created above.

name: Deploy Preview
run-name: Create a preview build 🚀

on: [pull_request]

env:
  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
  NEON_PROJECT_ID: ${{ vars.NEON_PROJECT_ID }}
  NEON_USERNAME: ${{ vars.NEON_USERNAME}}

jobs:
  deploy-preview:
    permissions: write-all
    runs-on: ubuntu-latest
    steps:
      - name: 🏗 Setup repo
        uses: actions/checkout@v4

      - name: 🚀 Create Neon Branch
        id: create-branch
        uses: neondatabase/create-branch-action@v5
        with:
          project_id: ${{ env.NEON_PROJECT_ID }}
          # parent: dev # optional (defaults to your primary branch)
          branch_name: preview/pr-${{ github.event.number }}-${{ github.event.pull_request.head.ref }}
          username: ${{ env.NEON_USERNAME }}
          database: dg_db # database to branch
          api_key: ${{ env.NEON_API_KEY }}

      - run: echo "EXPO_PUBLIC_NEON_URL=${{ steps.create-branch.outputs.db_url }}?sslmode=require" >> $GITHUB_ENV

      - name: 🏗 Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18.x
          cache: npm

      - name: 🏗 Setup Expo CLI
        uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}

      - name: 📦 Install dependencies
        run: npm install

      - name: 🚀 Create Expo preview
        uses: expo/expo-github-action/preview@v8
        with:
          command: eas update --auto --branch ${{ github.event.pull_request.head.ref }}

The first section defines the GitHub Actions name, the events it responds to (in this case, when a pull request is created), and the environment variables that will be used throughout the various GitHub Action steps.

name: Deploy Preview
run-name: Create a preview build 🚀

on: [pull_request]

env:
  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
  NEON_PROJECT_ID: ${{ vars.NEON_PROJECT_ID }}
  NEON_USERNAME: ${{ vars.NEON_USERNAME}}

jobs:
  deploy-preview:
    permissions: write-all
    runs-on: ubuntu-latest
    steps:
      - run: echo project_id ${{ env.NEON_PROJECT_ID}}

      - name: 🏗 Setup repo
        uses: actions/checkout@v4

The next section uses the Create Branch Action step provided by Neon to create a branch from our primary branch, using a specific pattern to create a unique branch name for the Neon database. Using this unique and reproducible pattern ensures it can be automatically deleted once the pull request is closed.

Once the branch is created, a new environment variable is created, EXPO_PUBLIC_NEON_URL, with the newly created database URL. The environment variable should be the same one used within your Expo application to connect to your Neon database. If it is not, update the variable name used in the GitHub Action to match what is used in your application.

- name: 🚀 Create Neon Branch
  id: create-branch
  uses: neondatabase/create-branch-action@v5
  with:
    project_id: ${{ env.NEON_PROJECT_ID }}
    # parent: dev # optional (defaults to your primary branch)
    branch_name: preview/pr-${{ github.event.number }}-${{ github.event.pull_request.head.ref }}
    username: ${{ env.NEON_USERNAME }}
    database: dg_db # database to branch
    api_key: ${{ env.NEON_API_KEY }}

- run: echo "EXPO_PUBLIC_NEON_URL=${{ steps.create-branch.outputs.db_url }}?sslmode=require" >> $GITHUB_ENV

Lastly, it configures the build environment for the Expo application, creates a preview build, publishes it to the Expo cloud for testing, and adds a comment to the pull request.

- name: 🏗 Setup Node
  uses: actions/setup-node@v3
  with:
    node-version: 18.x
    cache: npm

- name: 🏗 Setup Expo CLI
  uses: expo/expo-github-action@v8
  with:
    eas-version: latest
    token: ${{ secrets.EXPO_TOKEN }}

- name: 📦 Install dependencies
  run: npm install

- name: 🚀 Create Expo preview
  uses: expo/expo-github-action/preview@v8
  with:
    command: eas update --auto --branch ${{ github.event.pull_request.head.ref }}

The pull request comment added to the pull request is done as part of the Create Expo preview step. It contains information about the published app, such as the project name and platforms it was published to, as well as a QR code to open the preview build within the Expo Go app on your corresponding mobile device.

You’re now free to perform any actions on your preview app that would add, update, or modify data without fear of impacting or polluting data or resources in your production environment with test data.

Cleaning up the preview environment

Once the pull request has been merged, or closed, it is recommended to clean up the resources no longer needed, like the Neon database branch created when the pull request was made.

From the root directory of your Expo project, create a new GitHub Actions file in the GitHub workflows directory.

touch .github/workflows/cleanup-preview.yml

The following code defines the steps the GitHub Action will perform. Copy and paste this code into the file you created above.

name: Clean up Preview Deployment
on:
  pull_request:
    types: [closed]
env:
  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
  NEON_PROJECT_ID: ${{ vars.NEON_PROJECT_ID }}

jobs:
  delete-preview:
    runs-on: ubuntu-latest
    steps:
      - name: Delete Neon Branch
        uses: neondatabase/delete-branch-action@v3.1.5
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          branch: preview/pr-${{ github.event.number }}-${{ github.event.pull_request.head.ref }}
          api_key: ${{ secrets.NEON_API_KEY }}

The first section again defines the GitHub Actions name, the events it responds to (in this case, when a pull request is closed), and the environment variables that will be used throughout the various GitHub Action steps.

name: Clean up Preview Deployment
on:
  pull_request:
    types: [closed]

env:
  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
  NEON_PROJECT_ID: ${{ vars.NEON_PROJECT_ID }}

The last section deletes the Neon database branch created when the pull request was made using the same branch naming pattern when the pull request was made.

jobs:
  delete-preview:
    runs-on: ubuntu-latest
    steps:
      - name: Delete Neon Branch
        uses: neondatabase/delete-branch-action@v3.1.5
        with:
          project_id: ${{ env.NEON_PROJECT_ID }}
          branch: preview/pr-${{ github.event.number }}-${{ github.event.pull_request.head.ref }}
          api_key: ${{ env.NEON_API_KEY }}

And that’s all there is to it! When a pull request is merged or closed, its corresponding Neon database branch is deleted.

Conclusion

In this tutorial, you learned how to create a preview build of a React Native Expo application for each pull request made. You also learned how to create a corresponding Neon database branch for each preview build, passing its connection string along to the Expo application build process.

If you want to test this yourself, use the sample code and instructions on GitHub.