Integrate TiDB Cloud Branching (Beta) with GitHub

If you use GitHub for application development, you can integrate TiDB Cloud Branching into your GitHub CI/CD pipeline, which lets you automatically test your pull requests with branches without affecting the production database.

In the integration process, you will be prompted to install the TiDB Cloud Branching GitHub App. The app can automatically manage branches of your TiDB Cloud Starter or TiDB Cloud Essential instance according to pull requests in your GitHub repository. For example, when you create a pull request, the app will create a corresponding branch for your TiDB Cloud Starter or Essential instance, in which you can work on new features or bug fixes in isolation without affecting the production database.

This document covers the following topics:

1. How to integrate TiDB Cloud Branching with GitHub
2. How does the TiDB Cloud Branching app work
3. How to build a branching-based CI workflow to test every pull request using branches rather than the production TiDB Cloud Starter or Essential instance

Before you begin

Before the integration, make sure that you have the following:

• A GitHub account
• A GitHub repository for your application
• A TiDB Cloud Starter or TiDB Cloud Essential instance

Integrate TiDB Cloud Branching with your GitHub repository

To integrate TiDB Cloud Branching with your GitHub repository, take the following steps:

1. In the TiDB Cloud console, navigate to the My TiDB page, and then click the name of your target TiDB Cloud Starter or TiDB Cloud Essential instance to go to its overview page.

2. Click Branches in the left navigation pane.

3. In the upper-right corner of the Branches page, click Connect to GitHub.

   • If you have not logged into GitHub, you will be asked to log into GitHub first.
   • If it is the first time you use the integration, you will be asked to authorize the TiDB Cloud Branching app.
   

4. In the Connect to GitHub dialog, select a GitHub account in the GitHub Account drop-down list.

   If your account does not exist in the list, click Install Other Account, and then follow the on-screen instructions to install the account.

5. Select your target repository in the GitHub Repository drop-down list. If the list is long, you can search the repository by typing the name.

6. Click Connect to connect between your TiDB Cloud Starter or Essential instance and your GitHub repository.

   

TiDB Cloud Branching app behaviors

After you connect your TiDB Cloud Starter or TiDB Cloud Essential instance to your GitHub repository, for each pull request in this repository, the TiDB Cloud Branching GitHub App can automatically manage its corresponding branch for your TiDB Cloud Starter or Essential instance. The following lists the default behaviors for pull request changes:

Configure TiDB Cloud Branching app

To configure the behaviors of TiDB Cloud Branching app, you can add a tidbcloud.yml file to the root directory of your repository, and then add the desired configurations to this file according to the following instructions.

branch.blockList

Type: array of string. Default: [].

Specify the GitHub branches that forbid the TiDB Cloud Branching app, even if they are in the allowList.

github:
    branch:
        blockList:
            - ".*_doc"
            - ".*_blackList"

branch.allowList

type: array of string. Default: [.*].

Specify the GitHub branches that allow the TiDB Cloud Branching app.

github:
    branch:
        allowList:
            - ".*_db"

branch.mode

Type: string. Default: reset.

Specify how the TiDB Cloud Branching app handles branch updates:

• If it is set to reset, the TiDB Cloud Branching app will update the existing branch with the latest data.
• If it is set to reserve, the TiDB Cloud Branching app will create a new branch for your latest commit.

github:
    branch:
        mode: reset

branch.autoDestroy

Type: boolean. Default: true.

If it is set to false, the TiDB Cloud Branching app will not delete the branch for your TiDB Cloud Starter or TiDB Cloud Essential instance when a pull request is closed or merged.

github:
    branch:
        autoDestroy: true

Create a branching CI workflow

One of the best practices for using branches is to create a branching CI workflow. With the workflow, you can test your code using a branch of your TiDB Cloud Starter or Essential instance instead of using the production instance itself before merging the pull request. You can find a live demo here.

Here are the main steps to create the workflow:

1. Integrate TiDB Cloud Branching with your GitHub repository.

2. Get the branch connection information.

   You can use the wait-for-tidbcloud-branch action to wait for the readiness of the branch and get the connection information of the branch.

   Taking the branch of a TiDB Cloud Starter instance as an example:

   steps:
     - name: Wait for TiDB Cloud Starter branch to be ready
       uses: tidbcloud/wait-for-tidbcloud-branch@v0
       id: wait-for-branch
       with:
         token: ${{ secrets.GITHUB_TOKEN }}
         public-key: ${{ secrets.TIDB_CLOUD_API_PUBLIC_KEY }}
         private-key: ${{ secrets.TIDB_CLOUD_API_PRIVATE_KEY }}
   
     - name: Test with TiDB Cloud Starter branch
        run: |
           echo "The host is ${{ steps.wait-for-branch.outputs.host }}"
           echo "The user is ${{ steps.wait-for-branch.outputs.user }}"
           echo "The password is ${{ steps.wait-for-branch.outputs.password }}"
   

   • token: GitHub will automatically create a GITHUB_TOKEN secret. You can use it directly.
   • public-key and private-key: The TiDB Cloud API key.

3. Modify your test code.

   Modify your test code to accept the connection information from GitHub Actions. For example, you can accept the connection information through the environment, as demonstrated in the live demo.

What's next

Learn how to use the branching GitHub integration with the following examples:

• branching-gorm-example
• branching-django-example
• branching-rails-example

You can also build your branching CI/CD workflow without the branching GitHub integration. For example, you can use setup-tidbcloud-cli and GitHub Actions to customize your CI/CD workflows.