Release

After PR/MR approval and merge, your CI/CD pipeline triggers Bytebase to create a release and deploy the migrations.

Non-bot PR/MR authors observed by bytebase-release count as active VCS users against your plan’s user limit. See How Users Are Counted.

How Releases Work

A Release is an immutable package containing all your SQL migration files:

• Linked to VCS commit for full traceability
• Files validated and stored with SHA256 checksums
• Can be deployed to multiple environments
• Supports progressive rollout strategies

Inside Bytebase, the release triggers:

1. Plan Generation - Defines target databases and rollout strategy
2. Rollout Execution - Creates tasks for each database
3. Revision Tracking - Records applied migrations to prevent duplicates

CI/CD Integration Examples

Use a compatible bytebase-action image. For Bytebase Cloud, use bytebase/bytebase-action:cloud. For self-hosted Bytebase, replace :cloud with your Bytebase server version, for example :3.14.0.

GitHub Actions

# .github/workflows/release.yml
name: Database Release
on:
  push:
    branches: [main]
    paths:
      - 'migrations/**'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create Bytebase Release
        uses: bytebase/sql-review-action@v1
        with:
          command: rollout
          bytebase-url: ${{ secrets.BYTEBASE_URL }}
          bytebase-token: ${{ secrets.BYTEBASE_SERVICE_ACCOUNT_TOKEN }}
          file-pattern: 'migrations/**/*.sql'
          project: projects/my-project
          targets: instances/prod/databases/mydb

GitHub Tutorial

GitHub Example

GitLab CI

# .gitlab-ci.yml
rollout:
  image: bytebase/bytebase-action:cloud
  stage: deploy
  only:
    - main
  script:
    - |
      bytebase-action rollout \
        --url $BYTEBASE_URL \
        --service-account $BYTEBASE_SERVICE_ACCOUNT \
        --service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
        --file-pattern "migrations/**/*.sql" \
        --project projects/my-project \
        --targets instances/prod/databases/mydb

GitLab Tutorial

GitLab Example

Azure DevOps

# azure-pipelines.yml
trigger:
  branches:
    include:
      - main
  paths:
    include:
      - migrations/**

jobs:
  - job: Release
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - task: Docker@2
        inputs:
          command: run
          arguments: >
            -e BYTEBASE_URL=$(BYTEBASE_URL)
            -e BYTEBASE_SERVICE_ACCOUNT=$(BYTEBASE_SERVICE_ACCOUNT)
            -e BYTEBASE_SERVICE_ACCOUNT_SECRET=$(BYTEBASE_SERVICE_ACCOUNT_SECRET)
            -v $(System.DefaultWorkingDirectory):/workspace
            bytebase/bytebase-action:cloud
            rollout
            --file-pattern "/workspace/migrations/**/*.sql"
            --project projects/my-project
            --targets instances/prod/databases/mydb

Azure Tutorial

Azure Example

Bitbucket Pipelines

# bitbucket-pipelines.yml
pipelines:
  branches:
    main:
      - step:
          name: Database Release
          image: bytebase/bytebase-action:cloud
          deployment: production
          script:
            - |
              bytebase-action rollout \
                --url $BYTEBASE_URL \
                --service-account $BYTEBASE_SERVICE_ACCOUNT \
                --service-account-secret $BYTEBASE_SERVICE_ACCOUNT_SECRET \
                --file-pattern "migrations/**/*.sql" \
                --project projects/my-project \
                --targets instances/prod/databases/mydb

Bitbucket Tutorial

Bitbucket Example

Deployment Strategies

Progressive rollout across environments:

# Deploy to dev, then staging, then production
targets: >
  instances/dev/databases/mydb,
  instances/staging/databases/mydb,
  instances/prod/databases/mydb

Multi-tenant deployment using database groups:

# Deploy to entire production fleet
targets: projects/my-project/databaseGroups/production-fleet

Database Groups

Manage database fleets with groups

Idempotency Guarantee

Bytebase tracks which migration versions have been applied to each database via the revision system. When creating a release:

1. Check revisions - Query which versions already exist
2. Skip applied - Migrations with matching versions are skipped
3. Execute new - Only unapplied versions are executed
4. Record success - Create revision only on successful completion

This ensures:

• ✅ Safe to run the same release multiple times
• ✅ Migrations never double-execute
• ✅ Environment parity (dev migrations auto-skip in prod)

---

Next Steps

Limitations

Understand constraints and considerations

Best Practices

Production-ready workflow patterns