Release

After PR/MR approval and merge, your CI/CD pipeline creates a Release, a Plan referencing it, and a Rollout for execution. See Release for the resource definition and its relationship to Plan, or follow the GitOps tutorial for a complete example.

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

The deployment command coordinates these separate steps; creating a Release alone does not trigger them:

1. Plan Generation - References the Release and selects target databases
2. Rollout Creation - Creates stages and tasks for execution
3. Revision Tracking - Records successfully applied migration versions per database

Release-based Plans do not create the UI workflow’s review Issue or run its Plan checks. Run SQL Review in CI and repository review before deployment. Creating a Rollout does not establish that its tasks have run; see Rollout for execution and verification.

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. During execution:

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

Revision history is per database: a migration applied in Dev still runs in Prod if Prod has not applied it. If execution fails, inspect the task logs and database state before retrying; a failed attempt can leave partial changes.

A Release is immutable. Use a new Release for changed files and a new migration version to update a database that already applied the previous version. To continue an existing Plan through another environment, see promotion in the GitOps tutorial.

---

Next Steps

Limitations

Understand constraints and considerations

Best Practices

Production-ready workflow patterns