Integrating with GitLab CI

This tutorial will show you the steps to integrate Bytebase CLI bb into a GitLab project. You will set up a pipeline automating the database schema change along with the code change, which brings your team’s DevOps automation to a new level.


  • A GitLab Project. ( or GitLab CE/EE. We use for this tutorial.)
  • Self-managed GitLab Runner on a Linux machine. (You can follow the GitLab Runner docs to install)
  • A MySQL database that is network accessible by the GitLab Runner.

Install bb on GitLab Runner

On your GitLab Runner shell prompt, paste the following command:

/bin/bash -c "$(curl -fsSL"

Run bb --version to check if bb is installed.

You can go back to overview for more installation details.

Register GitLab Runner to a GitLab Project

In your GitLab Project, go to Settings > CI/CD > Runners, click the Show Runner Installation Instructions button, and follow the instructions to register runner.

register gitlab runner

From the shell prompt, add tag bb-runner to specify this runner has bb installed.

tag for gitlab runner

Configure GitLab CI

Set up .gitlab-ci.yml:

  - deploy

  tags: ['bb-runner'] # Runs this job on runners that has bb installed
  only: # Only trigger when a script added to dev/
    refs: ['main']
    changes: ['dev/*']
  stage: deploy
    - bb dump --dsn $BYTEBASE_DSN --schema-only --file before-migrate.sql # Snapshot the schema before migration
    - migrate_scripts=$(git diff-tree --no-commit-id --name-only -r $CI_COMMIT_SHA | grep '^dev/' -) # Extract the added files
    - |
      for migrate_script in $migrate_scripts; do
        bb migrate --dsn $BYTEBASE_DSN --file $migrate_script;
    - bb dump --dsn $BYTEBASE_DSN --schema-only --file after-migrate.sql # Snapshot the schema after migration

      - before-migrate.sql
      - after-migrate.sql
    expire_in: 30 days

Configure DSN

bb configures --dsn to access databases. Here are a few examples:

  • mysql://root@localhost:3306/
  • postgresql://user:pass@localhost:5432/dbname?ssl-ca=a&ssl-cert=b&ssl-key=c

You also need to setup DSN secret to make this workflow available: Go to Setting > CI/CD > Variables, add your DSN as BYTEBASE_DSN.

add dsn secret

add dsn secret

Trigger a Migration

Finally, you can trigger a migration by adding a new commit to your GitLab project.

Commit a script to dev/ and check if this job runs correctly:

gitlab job result

The schema snapshots before and after the migration are stored in artifacts:

gitlab job result

You can browse this job detail on

Edit this page on GitHub

Subscribe to Newsletter

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