Enable GitOps Workflow in Project


To enable GitOps workflow, project owner needs to link one of their Git repositories with their Bytebase project.

Estimate setup time: 15 minutes.

This guide will walk you through how to enable the GitOps workflow for a project in Bytebase. This is a reference setup showing what it will look like after the setup.


  • You should be the Project Owner to enable GitOps workflow in the project.


Go to the project you wish to enable GitOps workflow for. Choose GitOps and click Configure GitOps.


Step 1 - Choose Git provider


You can only link Git repository from one of the existing Git providers in Bytebase. If your desired Git provider is not there, you need to contact Workspace Admin to follow Add Git Provider to add it.

Click the Git provider hosting your repository, and Bytebase will start the OAuth process with your chosen Git provider. If you are not currently logged into that provider, you will be prompted to login first in order to complete the OAuth.


If you encounter errors during this process, it's likely the Git provider is not setup properly and you need to contact Workspace Admin to double check the setup following Add Git Provider.


Step 2 - Select repository

If the OAuth process is successful, you will be prompted to STEP 2: Select repository.


For GitLab, Bytebase only lists repositories where you have at least the Maintainer role. This is because to configure the VCS integration, Bytebase needs to create the webhook, which requires Maintainer role.


Select the repository you want to link to the Bytebase project.

Step 3 - Configure deploy


The final step allows you to configure the following settings:

Branch - Required

This is the branch where Bytebase observes the migration SQL file changes.


For GitLab, you can specify wildcards, such as "feature/*" to match branches starting with "feature/".

Base directory - Optional

Default: root directory

Bytebase only observes migration file changes under this directory and all its sub-directories. we recommend to create a dedicated directory called "bytebase" under the repository root to store all your Bytebase related migration files.

Click "Finish" button to complete the setup. Under the hood, this will create a webhook in the linked repository so that Bytebase can observe code changes.

Schema change type - Required

Default: Migration-based

Bytebase provides two schema change type:

  • Migration-based
  • State-based (Beta)

Migration-based schema change type allows user to apply schema change by DDL. State-based schema change type provides a declarative way to describe the desired state of the schema.

File path template - Required

Default: {{ENV_ID}}/{{DB_NAME}}##{{VERSION}}##{{TYPE}}##{{DESCRIPTION}}.sql

The file path template allows user to customize the file path format of the migration file. This path is relative to the base directory set above. The template supports following placeholders:

Required placeholders (must present in the template):

  • {{DB_NAME}} - Specify the database name.
  • {{VERSION}} - Specify the migration version.
  • {{TYPE}} - Specify the migration type. Can be either "ddl" for schema migration or "dml" for data migration. Alternatively, you can use the alias names "migrate" and "data" for "ddl" and "dml" respectively.

Optional placeholders

  • {{ENV_ID}} - Specify the lower-case environment identifier. This is useful to disambiguate the specified database if databases share the same name across different environments.
  • {{DESCRIPTION}} - Specify a description for the migration.

Check name and organize schema files for the recommended file path template.

Schema path template - Optional

Default: {{ENV_ID}}/.{{DB_NAME}}##LATEST.sql

When specified, after each migration, Bytebase will write the latest schema to this schema path relative to the base directory in the same branch as the original commit triggering the migration. Leave empty if you don't want Bytebase to do this.

💡 This is useful to let repository always keep a complete schema of the corresponding database.


Make sure the changed branch is not protected or allow repository maintainer to push to that protected branch. See protected branch.

Required placeholders (must present in the template if specified):

  • {{DB_NAME}} - Specify the database name.

Optional placeholders

  • {{ENV_ID}} - Specify the lower-case environment identifier. This is useful to disambiguate the specified database if databases share the same name across different environments.

Enable SQL Review CI - Optional

You can follow GitOps SQL Review CI to set up.

You have now enabled the GitOps workflow for your project. Bytebase will start observe SQL file changes from the linked repository. The last task is to name and organize the schema files in the linked repository directory so that Bytebase can figure out for a given SQL file change, which database it should apply to.


Edit this page on GitHub

Subscribe to Newsletter

By subscribing, you agree with Bytebase's Terms of Service and Privacy Policy.