> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Release

> Preserve SQL files as an immutable package that Plans can deploy.

A **Release** is an immutable package of database change files saved in a Bytebase project. It records their SQL contents, migration versions where applicable, and optional source links such as a commit or pull request. A Plan references the Release to use those files for a change.

For example, a Release can contain the migrations that add nickname and work-email columns to the sample employee table. The same Release can supply the files for deployment to Test and Prod, preserving the inputs across environments.

## Release versus Plan

A **Release** answers which files to use. A **Plan** specifies the work and its targets and tracks the change through deployment. The Release has no deployment targets of its own and can be referenced by multiple Plans. A UI Plan can also use SQL directly, without a Release.

Creating a Release saves the files. Execution happens through a Plan's [Rollout](/concepts/rollout), where each target has its own task results.

## What the files describe

A Release uses one of two change models:

* **Versioned migrations** describe changes to execute in order, such as creating a table and then adding a column. Bytebase records applied versions separately for each database and skips versions already applied there.
* **Declarative schema definitions** describe the desired schema. Bytebase compares them with each target's schema to generate the required changes. Different starting schemas can produce different SQL.

See [migration-based workflows](/gitops/migration-based-workflow/overview) and [state-based workflows](/gitops/state-based-workflow/overview) for file conventions, supported engines, and limitations.

## Create a Release

An integration creates a Release through the API. In the documented GitOps workflow, CI checks the files during pull-request review; after merge, the deployment job uses `bytebase-action rollout` to create the Release, a Plan referencing it, and the Rollout.

Release contents cannot be edited. Correct unapplied files in a new Release. If a migration has already run, add a new migration version to make the next change rather than editing the applied file.

## Deploy the same files across environments

A Plan that targets both Test and Prod can deploy the Release to Test first, then continue to Prod. The promotion job reuses the same Plan and Release.

<img src="https://mintcdn.com/dbx/qVFhwirzSyvmoIAn/content/docs/concepts/release-promotion-630d70d3.svg?fit=max&auto=format&n=qVFhwirzSyvmoIAn&q=85&s=95ee65df6b403e1d5a2c9b14e401ba67" alt="One Plan references an immutable Release and targets both hr_test and hr_prod, with Test and Prod stages in its Rollout" width="840" height="550" data-path="content/docs/concepts/release-promotion-630d70d3.svg" />

This is one way to organize promotion. A workflow can also use separate Plans referencing the same Release. When continuing an existing Plan with `--plan`, the command uses its recorded targets; it does not add Prod to a Test-only Plan. See [GitOps release and promotion](/gitops/migration-based-workflow/release).

## Inspect a Release

Open your project's **CI/CD → Releases** and select a Release to inspect its files, versions, and source links. Follow the Plan link from the deployment job to see which targets used those files and their execution results.

**Active** Releases appear in the normal list. **Archived** Releases are retained and can be restored. These states describe the Release's availability, not whether it has been deployed.

Follow the [GitOps tutorial](/gitops/migration-based-workflow/tutorial) for a complete example, or [GitOps troubleshooting](/gitops/troubleshooting/overview) to investigate a failed check or deployment job.
