Announcing the PlanetScale GitHub Actions
Easily integrate common PlanetScale operations directly into your GitHub Actions Workflows.

With our database branching and deploy request workflow, PlanetScale was built with DevOps pipelines in mind. However, anyone who’s worked in DevOps long enough knows it is a very “choose your own adventure” practice. While guidelines exist, many companies build their pipelines very differently according to the needs of the product. Integrating PlanetScale into this flow is no exception. Today, we’re lowering the barrier of entry by publishing the first wave of official PlanetScale GitHub Actions for you to use in your projects.
What are GitHub Actions?
Before we cover the available Actions, it’s worth taking a moment to understand what GitHub Actions is. GitHub Actions allows you to automate processes directly within your repository by defining jobs in YAML that will perform operations based on the triggers you define. These YAML files are referred to as “workflows”, whereas the individual operations within are called “steps”. Developers are free to write their own steps using bash or PowerShell manually, or they can search the GitHub Actions Marketplace for a pre-defined step that performs the operations they need without having to build the functionality themselves.
The PlanetScale GitHub Actions
We’ve built four GitHub Actions that will perform common operations on your PlanetScale database. We’ve also published them to the GitHub Actions Marketplace, making it easier for you to pull them into your application.
- The
create-branch-action
lets you create a branch of a PlanetScale database. - The
create-branch-password-action
will create a new password of a database branch and pipe the username, password, and hostname to respective outputs to use in other steps. - The
create-deploy-request-action
will create a Deploy Request between two branches and pipe the Deploy Request number to an output for you to use. - Finally, the
deploy-deploy-request-action
will attempt to merge the changes defined in an existing Deploy Request.
When used with the correct triggers, these actions can be combined in interesting ways to get the desired automation. Let’s take a look at two examples.
Create a new database branch when a GitHub branch is created
If your team opens a new database branch whenever a feature branch is created in your GitHub repository, you can combine the create-branch-action
and create-branch-password-action
in a workflow that triggers when a new branch is opened to do just that. The following YAML will trigger when a GitHub branch is created, and it will create a branch of the recipes_db
database that has the same name as the branch opened in GitHub.
name: Create a branch
on: create
jobs:
create_a_branch:
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@v3
- name: Extract branch name
shell: bash
run: echo "branch=$(echo ${GITHUB_REF#refs/heads/})" >> $GITHUB_OUTPUT
id: extract_branch
- name: Create a branch
uses: planetscale/create-branch-action@v1
id: create_branch
with:
org_name: my_org
database_name: recipes_db
branch_name: ${{ steps.extract_branch.outputs.branch }}
from: main
env:
PLANETSCALE_SERVICE_TOKEN_ID: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
PLANETSCALE_SERVICE_TOKEN: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}
- name: Create a password
uses: planetscale/create-branch-password-action@v1
id: create_branch_password
with:
org_name: my_org
database_name: recipes_db
branch_name: ${{ steps.extract_branch.outputs.branch }}
name: 'pass_${{ steps.extract_branch.outputs.branch }}'
env:
PLANETSCALE_SERVICE_TOKEN_ID: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
PLANETSCALE_SERVICE_TOKEN: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}
- name: Get the new credentials
run: |
echo "Hostname: ${{ steps.create_password.outputs.hostname }}"
echo "Username: ${{ steps.create_password.outputs.username }}"
echo "Password: ${{ steps.create_password.outputs.password }}"
Merging database changes when a pull request closes
Another common use of branches is to merge database schema changes from one branch to another (for example, a staging branch to a production branch) when a pull request closes. The following workflow sample will use create-deploy-request-action
and deploy-deploy-request-action
to automatically merge changes between database branches whose names match their corresponding GitHub counterparts.
name: Merge schema changes
on:
pull_request:
types: [closed]
jobs:
merge_changes:
runs-on: ubuntu-latest
if: github.event.pull_request.merged == true
steps:
- name: checkout
uses: actions/checkout@v3
- name: Create a deploy request
uses: planetscale/create-deploy-request-action@v1
id: create_deploy_request
with:
org_name: bmorrison-ps
database_name: recipes_db
branch_name: ${{ github.event.pull_request.head.ref }}
env:
PLANETSCALE_SERVICE_TOKEN_ID: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
PLANETSCALE_SERVICE_TOKEN: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}
- name: Deploy a deploy request
uses: planetscale/deploy-deploy-request-action@v1
with:
org_name: bmorrison-ps
database_name: recipes_db
number: ${{ steps.create_deploy_request.outputs.number }}
wait: true
env:
PLANETSCALE_SERVICE_TOKEN_ID: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
PLANETSCALE_SERVICE_TOKEN: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}
It’s worth noting that while this workflow will indeed merge changes between database branches in PlanetScale, it does not consider deploying the latest version of your application code. That said, make sure that you thoroughly test the timing between deploying application component updates to avoid any unnecessary downtime.
How to use the PlanetScale GitHub Actions
To get started using these Actions, visit the repository for the action you are interested in for more details on how to get started with that specific Action. If you are building your Actions from within the GitHub interface, you may also use the Marketplace located on the right side to search for these Actions.
- create-branch-action
- create-branch-password-action
- create-deploy-request-action
- deploy-deploy-request-action
If you have another official PlanetScale GitHub Action you would like to see, tweet at us @planetscale or post in discussions to let us know and we will look into it for the future actions.
We also have a repository with a collection of scripts that can be utilized in your own GitHub Actions workflows with the PlanetScale CLI. Check out our article on how to use these scripts for more information, including several real-world examples.