Setting up GitHub Codespaces with Neon Database Branching for Pull Requests
Learn how to create separate development environments for each pull request using GitHub Codespaces and Neon's Postgres branching
When working on a team project, it's useful to have separate environments for each new feature or bug fix. This helps prevent conflicts and makes it easier to test changes. In this guide, we'll show you how to set up a process that creates a new development environment for each pull request. We'll use GitHub Codespaces for the coding environment and Neon's Postgres branching for the database.
By the end of this guide, you'll have a setup that automatically creates a new Codespace and a new database branch for each pull request. This means each change can be tested separately, making it easier to find and fix problems.
What you'll need
Before we start, make sure you have:
- A GitHub account that can use Codespaces
- A Neon account and project
- A Neon API key (you can learn how to get one here)
- Basic knowledge of Git, GitHub Actions, and CI/CD
Creating a new project
This process will work with any language or framework, but for this guide, we'll use Laravel.
Let's start by making a new Laravel project and putting it on GitHub.
- First, create a new Laravel project:
This command creates a new Laravel project in a folder called codespaces-neon-demo
then uses cd
to access the new project.
- Next, set up Git for this project:
The above commands will initialize a new Git repository, add all the project files to it, and create the first commit.
- Now, create a new repository on GitHub and upload your code:
Replace yourusername
with your actual GitHub username. These commands connect your local repository to GitHub and upload your code.
Setting up GitHub Codespaces
Now we'll set up GitHub Codespaces. This will define the development environment that will be created for each pull request.
- Make a new folder in your project for the Codespaces configuration:
- In this new folder, create a file called
devcontainer.json
:
This file tells GitHub Codespaces how to set up the development environment. Here's what each part does:
"name"
: This is just a name for the Codespace."image"
: This specifies the base Docker image to use. We're using a pre-built image with PHP 8.2."customizations"
: This section lists VS Code extensions to install."forwardPorts"
: This tells Codespaces which ports to make available."postCreateCommand"
: This runs commands after the Codespace is created. It installs PHP dependencies, generates an application key, and runs a setup script for the database."features"
: This adds Node.js to the environment.
Setting up Neon Postgres
Now let's connect our project to a Neon Postgres database.
-
Go to the Neon Console and create a new project.
-
After creating the project, you'll see a connection string. Copy the details as you'll need them later.
-
Open the
.env
file in your Laravel project and update the database settings:
Replace the placeholders with the details from your Neon connection string.
- Run the database migrations:
This command creates the necessary tables in your Neon database.
Setting up GitHub Actions for Neon Branching
Now we'll set up GitHub Actions to create and delete Neon database branches automatically. First, we need to add your Neon API key to your GitHub repository:
- In your GitHub repository, go to "Settings", then "Secrets and variables", then "Actions".
- Click "New repository secret".
- Name it
NEON_API_KEY
and paste your Neon API key as the value. - Click "Add secret".
Next, we'll create two GitHub Actions workflows: one to create a new Neon branch when a pull request is opened, and another to delete the branch when the pull request is closed.
Workflow to Create a Branch
If you don't already have a .github/workflows
directory, create one:
Then create a file in this directory called create-neon-branch.yml
with the following content:
Replace your-neon-project-id
and your-database-username
with your actual Neon project ID and database username.
This workflow does the following:
- It runs when a pull request is opened or reopened thanks to the
on
section. - It uses Neon's official action to create a new database branch.
- The branch name is based on the pull request number.
- It outputs the new branch's database URL and ID.
Workflow to Delete a Branch
With the workflow to create a branch set up, let's create another one to delete the branch when the pull request is closed.
Create another file at .github/workflows/delete-neon-branch.yml
:
Again, replace your-neon-project-id
with your actual Neon project ID.
This workflow:
- Runs when a pull request is closed.
- Uses Neon's action to delete the database branch associated with the pull request.
Configuring Codespaces to Use Neon Branches
Now we need to tell Codespaces how to connect to the right database branch. Create a file called setup-db.sh
in the .devcontainer
directory:
The script does the following:
- It checks if we're in a pull request environment.
- If we are, it gets the details of the newly created database branch.
- It updates the
.env
file with these details. - Finally, it runs database migrations.
Make sure to make this script executable:
After setting up these files, commit and push your changes to GitHub:
With everything set up, you can now create a new branch in your project, open a pull request, and see the new Codespace and database branch in action.
How to Use This Setup
With everything set up, here's how you would use this in your development process:
-
Create a new branch in your project and make your changes:
- Create and switch to a new branch:
git checkout -b feature-branch-name
- Make your changes to the code
- Commit your changes:
git add .
andgit commit -m "Description of changes"
- Push your branch to GitHub:
git push -u origin feature-branch-name
- Create and switch to a new branch:
-
Open a pull request with your changes:
- Go to your repository on GitHub
- Click on "Pull requests" then "New pull request"
- Select your feature branch as the compare branch
- Click "Create pull request"
- Fill in the title and description, then click "Create pull request"
-
GitHub Actions will automatically create a new Neon database branch for your pull request:
- This happens automatically when the pull request is opened
- You can check the "Actions" tab in your GitHub repository to see the progress
- Once complete, you'll see a new branch in your Neon console named
pr-[number]
-
Open a Codespace for this pull request:
- On the pull request page, click the "Code" dropdown
- Select "Open with Codespaces"
- Click "New codespace"
- Wait for the Codespace to build and start
-
Test your changes in the isolated environment:
- The Codespace is now connected to your PR-specific database branch
- Run your application:
php artisan serve
- Run tests:
php artisan test
- Make additional changes if needed, commit, and push
-
Review and merge the pull request:
- Once you're satisfied with the changes, request a review if required
- Reviewers can open their own Codespaces to test the changes
- When ready, merge the pull request on GitHub
-
Automatic cleanup:
- When the pull request is closed (either merged or declined), GitHub Actions will automatically delete the associated Neon database branch
- You can verify this in your Neon console
Keeping Things Secure
It's important to keep your project and its data safe:
- Never share your Neon API key. Always use GitHub Secrets to store it.
- Be careful about what information you put in public repositories.
- Regularly change your API keys and check who has access to what.
Conclusion
By setting up GitHub Codespaces with Neon database branching, you've created a system that gives each pull request its own complete development environment. This can help your team work more effectively by making it easier to test changes and avoid conflicts.
This workflow can be adapted to work with other languages and frameworks. You can also add more steps to the GitHub Actions workflows to suit your specific needs like running tests, deploying to staging environments, or sending notifications.
Where to Learn More
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.