GitHub with Xata

The Xata GitHub app promotes a collaborative Git-based workflow by managing all the necessary operations to keep your database in sync with your codebase. It also simplifies the creation of preview branches for all your pull requests.

When you connect your application repo to your Xata database, Xata will take care of several steps for you. First, Xata will create a preview branch for all new pull requests. These preview branches contain a subset of the main (production) branch data, with up to 10,000 rows copied over from it. Additionally, any migrations present in the code will be executed to ensure that the branch follows the schema in the code.

After a pull request is merged, Xata will migrate the main branch if there are any new migrations. This helps ensure that your main branch stays up to date with the latest changes to your schema.

Check our suggested workflow for a full guide on how to use the Xata CLI, Xata GitHub integration and some app hosting services together.

On any database view, click the Settings link near the top of the page and click into the GitHub integration. If you missed the last step about connecting your GitHub account, you'll need to follow the links provided to first connect your account.

Xata's GitHub application needs to be installed either at the user level (for personal repository access) or at the organization level (for access to your team repositories). Adding the application to both will allow you to link your Xata database to repos from either source.

Once permissions are granted you should see a list of GitHub repositories that you can connect to your database to. You can only connect one repository to a Xata database. Clicking connect will tell the Xata app to keep everything in sync within that repository.

After connecting a database to a GitHub repository, Xata will create and maintain a preview branch for every pull request that is opened. The preview branch will contain a subset of the data present in the main Xata branch, and follow the schema present in the pull request. The process for creating the preview branch is as follows:

• A new preview branch will be created (if it doesn't exist) by forking main schema, the preview branch will be named preview-<owner>-<branch_name>, where <owner> is the user/organization were the pull request base branch is located and <branch_name> is the name of the branch.
• When the preview is created for the first time, part of the data from the main branch will be copied over to it. This will be done by copying up to 10,000 rows from the main branch.
• If there are new migrations added by the pull request (under the .xata/migrations folder), they will be executed on the preview branch.

Every new push to the pull request will trigger these steps again, so the Xata preview branch will always be up to date with the latest changes in the pull request.

Once a pull request is merged, the preview branch will be automatically deleted.

When a pull request is merged, Xata will migrate the main branch if there are any new migrations under the .xata/migrations folder. This helps ensure that your main branch stays up to date with the latest changes to your schema.

Xata will add a status check to every pull request with a preview branch attached to it. The status check will have one of the following states:

• Pending: The preview branch is being created or updated.
• Success: The preview branch is up to date with the pull request.
• Failure: There was an error while creating or updating the preview branch.

In the case of errors, Xata will add a comment to the pull request with more information about the error.