Skip to main content

Documentation Index

Fetch the complete documentation index at: https://xata.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

This workflow creates a dedicated Xata branch for each pull request, allowing you to test database changes in isolation. It also manages PR comments to provide branch information and status updates.

​
Workflow Configuration

name: Create Xata dev branch

on:
  pull_request:
    ignore-branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  FORCE_COLOR: 3
  XATA_API_KEY: ${{ secrets.XATA_API_KEY }}
  XATA_ORGANIZATIONID: 123xyz
  XATA_PROJECTID: prj_i3qsq56h3p3d3crnk7htnc75d0
  XATA_BRANCHID: s99l2grl6d3nr1cqcbaaa5piic
  XATA_BRANCHNAME: main
  XATA_DATABASENAME: app

permissions:
  id-token: write
  contents: write
  packages: write
  pages: write
  pull-requests: write

​
Authentication and Environment Variables

The workflow requires several environment variables to be set:
  • XATA_API_KEY: Your Xata API key (set as a GitHub secret)
  • XATA_ORGANIZATIONID: Your Xata organization ID
  • XATA_PROJECTID: Your Xata project ID
  • XATA_BRANCHID: The ID of the main branch
  • XATA_BRANCHNAME: The name of the main branch
  • XATA_DATABASENAME: Your database name
If you have the Xata CLI configured with your project locally, you can obtain these values with the following commands: 
# XATA_API_KEY
xata keys organization create

# XATA_ORGANIZATIONID
xata organization get id

# XATA_PROJECTID
xata project get id

# XATA_BRANCHID
xata branch get id

​
Required Permissions

The workflow requires the following GitHub permissions: 
permissions:
  id-token: write
  contents: write
  packages: write
  pages: write
  pull-requests: write

​
Workflow Steps

​
1. Find Previous Comment

- name: Find Previous Comment
  id: find-comment
  uses: peter-evans/find-comment@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    issue-number: ${{ github.event.pull_request.number }}
    comment-author: "github-actions[bot]"
    body-includes: "Xata Dev Branch"
This step searches for any existing comments from the workflow to update them later.

​
2. Checkout Code

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
    persist-credentials: false
This step checks out your repository code with full history and proper credentials configuration.

​
3. Install Dependencies

- name: Install pnpm
  uses: pnpm/action-setup@v2
  with:
    version: 10

- name: Install Xata CLI
  run: |
    curl -fsSL https://xata.io/install.sh | bash
    echo "/home/runner/.config/xata/bin" >> $GITHUB_PATH
These steps install the required dependencies:
  • pnpm package manager
  • Xata CLI

​
4. Check Status and Migration State

- name: Check Xata Status
  run: |
    xata status
    xata roll status
    xata branch view

- name: Check Xata main branch pgroll status
  id: xata-main-branch-roll-status
  run: |
    echo XATA_MAIN_BRANCH_ROLL_STATUS=`xata roll status | jq -r '.status'` >> $GITHUB_OUTPUT
These steps verify the current state of your Xata environment and check for any pending migrations.

​
5. Create or Update Comment

- name: Create or Update Comment
  id: create_comment
  uses: peter-evans/create-or-update-comment@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    comment-id: ${{ steps.find-comment.outputs.comment-id }}
    issue-number: ${{ github.event.pull_request.number }}
    edit-mode: replace
    body: |
      ### Xata Dev Branch

      Creating Xata Dev Branch for commit: ${{ github.sha }}
      Branch name: ${{ github.head_ref }}_${{ github.event.pull_request.number }}

      *Please wait for the comment to be updated with branch details.*

​
6. Branch Management

- name: Delete Any Existing Xata Dev Branch
  run: xata branch delete ${{ github.head_ref }}_${{ github.event.pull_request.number }} --yes
  continue-on-error: true

- name: Create Xata Dev Branch
  run: xata branch create --name ${{ github.head_ref }}_${{ github.event.pull_request.number }}

- name: Checkout Xata Dev Branch
  run: |
    echo XATA_BRANCHID=`xata branch get ${{ github.head_ref }}_${{ github.event.pull_request.number }} id` >> $GITHUB_ENV

​
7. Migration Handling

- name: Complete Any Pending Migrations
  if: ${{ steps.xata-main-branch-roll-status.outputs.XATA_MAIN_BRANCH_ROLL_STATUS == 'In progress' }}
  run: |
    xata roll complete

- name: Apply Xata Roll Migrations
  run: xata roll migrate

​
8. Environment Setup

- name: Get Latest Schema
  id: xata-roll-get-latest-schema
  run: |
    echo LATEST_SCHEMA=`xata roll latest --with-schema=true` >> $GITHUB_OUTPUT

- name: Setup New Preview Environment
  run: |
    echo DATABASE_URL=`xata branch url` >> $GITHUB_ENV
    echo SEARCH_PATH=${{ steps.xata-roll-get-latest-schema.outputs.LATEST_SCHEMA }} >> $GITHUB_ENV

​
9. Final Comment Update

- name: Update Comment with Branch Details
  uses: peter-evans/create-or-update-comment@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    comment-id: ${{ steps.find-comment.outputs.comment-id }}
    issue-number: ${{ github.event.pull_request.number }}
    edit-mode: replace
    body: |
      ### Xata Dev Branch

      Created Xata Dev Branch for commit: ${{ github.sha }}
      Branch name: ${{ github.head_ref }}_${{ github.event.pull_request.number }}

      Set the following schemas as the search_path:
          ${{ steps.xata-roll-get-latest-schema.outputs.LATEST_SCHEMA }}

      You can drop into the psql shell for this branch with:
          xata branch checkout ${{ github.head_ref }}_${{ github.event.pull_request.number }}
          psql `xata branch url`

      Branch URL: [View in Console](https://console.xata.io/organizations/123xyz/projects/prj_i3qsq56h3p3d3crnk7htnc75d0/branches/s99l2grl6d3nr1cqcbaaa5piic)

​
Concurrency Control

The workflow uses GitHub Actions concurrency to prevent multiple runs from interfering with each other: 
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
This ensures that:
  • Only one workflow run per PR is active at a time
  • New runs cancel any in-progress runs
  • Prevents race conditions during branch creation

​
When to Use

Use this workflow when you want to:
  • Create isolated database environments for PRs
  • Test database changes in isolation
  • Provide preview environments for PR reviewers
  • Automate database branch management

​
Best Practices

  1. Set Appropriate Timeout
    • The workflow has a 10-minute timeout
    • Adjust based on your typical migration duration
  2. Use Environment Variables
    • Store sensitive information in GitHub secrets
    • Use environment variables for configuration
  3. Handle Migration States
    • Check for in-progress migrations
    • Complete pending migrations
    • Apply new migrations
  4. PR Communication
    • Keep PR comments updated
    • Provide clear connection instructions
    • Include relevant warnings