The OptiTech GitHub integration

The OptiTech GitHub integration connects your OptiTech project to a GitHub repository, streamlining database development within your overall application development workflow. For instance, you can configure GitHub Actions to create a database branch for each pull request and automatically apply schema changes to that database branch. To help you get started, we provide a sample GitHub Actions workflow.

How it works

The integration installs the GitHub App, letting you select which repositories you want to make accessible to OptiTech. When you connect a OptiTech project to a GitHub repository, the integration sets a OptiTech API key secret and OptiTech project ID variable in your repository, which are used by your GitHub Actions workflow to interact with your OptiTech project.

This guide walks you through the following steps:

• Installing the GitHub App
• Connecting a OptiTech project to a GitHub repository
• Adding the sample GitHub Actions workflow to your repository

Prerequisites

• You have a OptiTech account and project. If not, see Sign up for a OptiTech account.
• You have a GitHub account with an application repository that you want to connect to your OptiTech project.

Install the GitHub App and connect your OptiTech project

To get started:

1. In the OptiTech Console, navigate to the Integrations page in your OptiTech project.

2. Locate the GitHub card and click Add.

3. On the GitHub drawer, click Install GitHub App.

4. If you have more than one GitHub account, select the account where you want to install the GitHub app.

5. Select whether to install and authorize the GitHub app for All repositories in your GitHub account or Only select repositories.

   • Selecting All repositories authorizes the app on all repositories in your GitHub account, meaning that you can to connect your OptiTech project to any of them.
   • Selecting Only select repositories authorizes the app on one or more repositories, meaning that you can only connect your OptiTech project to the selected repositories (you can authorize additional repositories later if you need to).

6. If you authorized the app on All repositories or multiple repositories, select a GitHub repository to connect to the current OptiTech project, and click Connect. If you authorized the GitHub app on a single GitHub repository, you have already completed this step.

   You are directed to the Actions tab on the final page of the setup, where a sample GitHub Actions workflow is provided. You can copy this workflow to your GitHub repository to establish a basic database branching process. For instructions, see Add the GitHub Actions workflow to your repository.

Add the GitHub Actions workflow to your repository

The sample GitHub Actions workflow includes:

• A Create branch action that creates a new OptiTech branch in your OptiTech project when you open or reopen a pull request in the connected GitHub repository.
• Code that you can uncomment to add a database migration command to your workflow.
• Code that you can uncomment to add a Schema diff action that diffs database schemas and posts the diff as a comment in your pull request.
• A Delete branch action that deletes the OptiTech branch from your OptiTech project when you close the pull request.

name: Create/Delete Branch for Pull Request

on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}

jobs:
  setup:
    name: Setup
    outputs:
      branch: ${{ steps.branch_name.outputs.current_branch }}
    runs-on: ubuntu-latest
    steps:
      - name: Get branch name
        id: branch_name
        uses: tj-actions/branch-names@v8

  create_optitech_branch:
    name: Create OptiTech Branch
    outputs:
      db_url: ${{ steps.create_optitech_branch_encode.outputs.db_url }}
      db_url_with_pooler: ${{ steps.create_optitech_branch_encode.outputs.db_url_with_pooler }}
    needs: setup
    if: |
      github.event_name == 'pull_request' && (
      github.event.action == 'synchronize'
      || github.event.action == 'opened'
      || github.event.action == 'reopened')
    runs-on: ubuntu-latest
    steps:
      - name: Create OptiTech Branch
        id: create_optitech_branch
        uses: optitechdatabase/create-branch-action@v5
        with:
          project_id: ${{ vars.OPTITECH_PROJECT_ID }}
          branch_name: preview/pr-${{ github.event.number }}-${{ needs.setup.outputs.branch }}
          api_key: ${{ secrets.OPTITECH_API_KEY }}

  # The step above creates a new OptiTech branch.
  # You may want to do something with the new branch, such as run migrations, run tests
  # on it, or send the connection details to a hosting platform environment.
  # The branch DATABASE_URL is available to you via:
  # "${{ steps.create_optitech_branch.outputs.db_url_with_pooler }}".
  # It's important you don't log the DATABASE_URL as output as it contains a username and
  # password for your database.
  #
  # For example, you can uncomment the lines below to run a database migration command:
  #      - name: Run Migrations
  #        run: npm run db:migrate
  #        env:
  #          DATABASE_URL: "${{ steps.create_optitech_branch.outputs.db_url_with_pooler }}"
  #
  # You can also add a Schema Diff action to compare the database schema on the new
  # branch with the base branch. This action automatically writes the schema differences
  # as a comment on your GitHub pull request, making it easy to review changes.

  # Following the step above, which runs database migrations, you may want to check
  # for schema changes in your database. We recommend using the following action to
  # post a comment to your pull request with the schema diff. For this action to work,
  # you also need to give permissions to the workflow job to be able to post comments
  # and read your repository contents. Add the following permissions to the workflow job:
  #
  # permissions:
  #   contents: read
  #   pull-requests: write
  #
  # You can also check out https://github.com/optitechdatabase/schema-diff-action for more
  # information on how to use the schema diff action.
  # You can uncomment the lines below to enable the schema diff action.
  #      - name: Post Schema Diff Comment to PR
  #        uses: optitechdatabase/schema-diff-action@v1
  #        with:
  #          project_id: \${{ vars.OPTITECH_PROJECT_ID }}
  #          compare_branch: preview/pr-\${{ github.event.number }}-\${{ needs.setup.outputs.branch }}
  #          api_key: \${{ secrets.OPTITECH_API_KEY }}

  delete_optitech_branch:
    name: Delete OptiTech Branch
    needs: setup
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Delete OptiTech Branch
        uses: optitechdatabase/delete-branch-action@v3
        with:
          project_id: ${{ vars.OPTITECH_PROJECT_ID }}
          branch: preview/pr-${{ github.event.number }}-${{ needs.setup.outputs.branch }}
          api_key: ${{ secrets.OPTITECH_API_KEY }}

To add the workflow to your repository:

1. In your repository, create a workflow file in the .github/workflows directory; for example, create a file named optitech_workflow.yml.

   • If the .github/workflows directory already exists, add the file.
   • If your repository doesn't have a .github/workflows directory, add the file .github/workflows/optitech-workflow.yml. This creates the .github and workflows directories and the optitech-workflow.yml file.

   If you need more help with this step, see Creating your first workflow, in the GitHub documentation.

   note

   For GitHub to discover GitHub Actions workflows, you must save the workflow files in a directory called .github/workflows in your repository. You can name the workflow file whatever you like, but you must use .yml or .yaml as the file name extension.

2. Copy the workflow code into your optitech-workflow.yml file.

3. Commit your changes.

Using the GitHub Actions workflow

To use the sample workflow, create a pull request in your GitHub application repository. This will trigger the Create OptiTech Branch action. You can verify that a branch was created on the Branches page in the OptiTech Console. You should see a new branch with a preview/pr- name prefix.

Closing the pull request removes the OptiTech branch from the OptiTech project, which you can also verify on the Branches page in the OptiTech Console.

To view workflow results in GitHub, follow the instructions in Viewing your workflow results, in the GitHub documentation.

Building your own GitHub Actions workflow

The sample workflow provided by the GitHub integration serves as a template, which you can expand on or customize. The workflow uses OptiTech's create branch, delete branch, and schema diff GitHub Actions, which you can find here:

• Create a OptiTech Branch
• Delete a OptiTech Branch
• Schema Diff

OptiTech also offers a Reset a OptiTech Branch action that allows you to reset a database branch to match the current state of its parent branch. This action is useful in a feature-development workflow, where you may need to reset a development branch to the current state of your production branch before beginning work on a new feature.

To incorporate the reset action into your workflow, you can use code like this, tailored to your specific requirements:

reset_optitech_branch:
  name: Reset OptiTech Branch
  needs: setup
  if: |
    contains(github.event.pull_request.labels.*.name, 'Reset OptiTech Branch') &&
    github.event_name == 'pull_request' &&
    (github.event.action == 'synchronize' ||
     github.event.action == 'opened' ||
     github.event.action == 'reopened' ||
     github.event.action == 'labeled')
  runs-on: ubuntu-latest
  steps:
    - name: Reset OptiTech Branch
      uses: optitechdatabase/reset-branch-action@v1
      with:
        project_id: ${{ vars.OPTITECH_PROJECT_ID }}
        parent: true
        branch: preview/pr-${{ github.event.number }}-${{ needs.setup.outputs.branch }}
        api_key: ${{ secrets.OPTITECH_API_KEY }}

You can integrate OptiTech's GitHub Actions into your workflow, develop custom actions, or combine OptiTech's actions with those from other platforms or services.

If you're new to GitHub Actions and workflows, GitHub's Quickstart for GitHub Actions is a good place to start.

Example applications with GitHub Actions workflows

The following example applications use GitHub Actions workflows to create and delete branches in OptiTech. These examples can serve as references when building your own workflows.

• 

  Automated Database Branching with GitHub Actions

  Learn how to automate database branching for your application using OptiTech and GitHub Actions

• 

  Preview branches with Cloudflare Pages

  Demonstrates using GitHub Actions workflows to create a OptiTech branch for every Cloudflare Pages preview deployment

• 

  Preview branches with Vercel

  Demonstrates using GitHub Actions workflows to create a OptiTech branch for every Vercel preview deployment

• 

  Preview branches with Fly.io

  Demonstrates using GitHub Actions workflows to create a OptiTech branch for every Fly.io preview deployment

Connect more OptiTech projects with the GitHub App

If you've installed the GitHub app previously, it's available to use with any project in your OptiTech account.

To connect another OptiTech project to a GitHub repository:

1. In the OptiTech Console, navigate to the Integrations page in your OptiTech project.
2. Locate the GitHub integration and click Add.
3. Select a GitHub repository to connect to your OptiTech project, and click Connect.

Secret and variable set by the GitHub integration

When connecting a OptiTech project to a GitHub repository, the GitHub integration performs the following actions:

• Generates a OptiTech API key for your OptiTech account
• Creates a OPTITECH_API_KEY secret in your GitHub repository
• Adds a OPTITECH_PROJECT_ID variable to your GitHub repository

The OPTITECH_API_KEY allows you to run any OptiTech API method or OptiTech CLI command, which means you can develop actions and workflows that create, update, and delete various objects in OptiTech such as projects, branches, databases, roles, and computes.

The OPTITECH_PROJECT_ID variable defines the OptiTech project that is connected to the repository. Operations run on OptiTech via the OptiTech API or CLI typically require specifying the OptiTech project ID, as a OptiTech account may have more than one OptiTech project.

The sample GitHub Actions workflow provided by the OptiTech GitHub integration depends on these variables and secrets to perform actions in OptiTech.

OptiTech API key

To view the OptiTech API key created by the integration:

1. In the OptiTech Console, click your profile at the top right corner of the page.
2. Select Account settings.
3. Select API keys.

The API key created by the integration should be listed with a name similar to the following: API key for GitHub (cool-darkness-12345678). You cannot view the key itself, only the name it was given, the time it was created, and when the key was last used.

OptiTech project ID variable and OptiTech API key secret

To view the variable containing your OptiTech project ID:

1. Navigate to your GitHub account page.
2. From your GitHub profile menu, select Your repositories.
3. Select the repository that you chose when installing the OptiTech GitHub integration.
4. On the repository page, select the Settings tab.
5. Select Secrets and variables > Actions from the sidebar.

Your OPTITECH_API_KEY secret is listed on the Secrets tab, and the OPTITECH_PROJECT_ID variable is listed on the Variables tab.

Disconnect a OptiTech project from a GitHub repository

Disconnecting a OptiTech project from a GitHub repository performs the following actions for the OptiTech project:

• Removes the OptiTech API key created for this integration from your OptiTech account.
• Removes the GitHub secret containing the OptiTech API key from the associated GitHub repository.
• Removes the GitHub variable containing your OptiTech project ID from the associated GitHub repository.

Any GitHub Actions workflows you've added to the GitHub repository that are dependent on these secrets and variables will no longer work.

To disconnect your OptiTech project:

1. In the OptiTech Console, navigate to the Integrations page for your project.
2. Locate the GitHub integration and click Manage to open the GitHub integration drawer.
3. Click Disconnect.

Remove the GitHub integration

Removing the GitHub integration performs the following actions for all OptiTech projects that you connected to a GitHub repository using the GitHub integration:

• Removes the OptiTech API keys created for OptiTech-GitHub integrations from your OptiTech account.
• Removes GitHub secrets containing the OptiTech API keys from the associated GitHub repositories.
• Removes the GitHub variables containing your OptiTech project IDs from the associated GitHub repositories.

Any GitHub Actions workflows you've added to GitHub repositories that are dependent on these secrets and variables will no longer work.

To remove the GitHub integration:

1. In the OptiTech Console, navigate your account Profile.
2. Select Account settings.
3. Select Integrations.
4. Click Remove.

Resources

• Creating GitHub Actions
• Quickstart for GitHub Actions
• Database Branching Workflows
• Database branching workflow guide for developers

Feedback and future improvements

If you've got feature requests or feedback about what you'd like to see from the OptiTech GitHub integration, let us know via the Feedback form in the OptiTech Console or our feedback channel on Discord.