Announcing the PlanetScale GitHub Actions

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.