Promotions

Available to: Developers, Admins Minimum plan: Free (all plans include branching and promotions)

A promotion moves table definition changes from one branch to another — typically from a developer's branch into main (or into test, if your team uses a test branch). Promotions include a diff review and an approval workflow, so structural changes are reviewed before they reach shared environments.

When a promotion completes, TitanRDM creates a deployment for every environment the target branch deploys to. For example, promoting into main creates one deployment for Stage and one for Prod, which you then deploy when ready.

Promotion show page

Why Promote?

Promotions move changes between branches in a controlled way. They provide:

Visibility — every change is diffed and displayed for review before it moves
Accountability — promotions record who requested, who approved, and when
Safety — an approver on the target branch must sign off before changes are applied
Auditability — a full action history is maintained for each promotion
Separation — separates the responsibility of making changes from the responsibility of approving them

The Promotion Lifecycle

Created → Requested → Promoted or...
                       ├── Rejected
                       ├── Cancelled
                       ├── Failed → (Retry)
                       └── Abandoned

Status	Meaning
Created	The promotion has been prepared with a list of table definitions to move.
Requested	A notification has been sent to approvers on the target branch.
Promoted	The table definitions have been copied to the target branch, and deployments have been created for its environments.
Rejected	An approver reviewed and rejected the promotion.
Cancelled	The creator cancelled the promotion before it was approved.
Failed	An error occurred during the promotion. Can be retried.
Abandoned	The promotion was discarded.

Creating a Promotion

Promotions go from the branch of your current environment to its parent branch.

Use the Environment chooser to switch to your development environment (its branch is shown on the Table Definitions page)
Navigate to Development > Promotions, or select tables on the Table Definitions page and click Promote
Click New Promotion
Choose the table definitions to include
Optionally enter a description and a pull request: the pull request with the matching data platform code changes, for example my-org/data-platform#42
Click Create Promotion

The pull request can also be added or changed later from the promotion's page. When it is merged, your CI/CD pipeline can promote the promotion and deploy it with each release; see CI/CD Integration.

Branches with no parent, such as main, have nothing to promote to, so the Table Definitions pages do not offer Promote for them. Environments of shared branches receive their deployments from promotions; the Table Definitions pages offer Deploy only on development branches.

The Diff Review

The promotion page shows a diff organised by table definition:

Diff Level	What It Shows
Table changes	Whether the table is being created, updated, or deleted on the target branch
Table attribute changes	Changes to table properties (name, database table name, domain, description, load type, etc.)
Column changes	Columns being added, modified, or removed
Column attribute changes	Changes to column properties (name, data type, primary key, foreign key, length, scale, etc.)
Import mapping changes	Changes to import definitions and column mappings associated with the table

Promotion diff review

Approval Actions

Promote

Copies the table definitions from the source branch to the target branch, then creates a deployment for each environment the target branch deploys to. The Deployments panel on the promotion page links to each one. Only enabled for approvers of the target branch.

Send Promotion Request

If you are not an approver of the target branch, this sends a promotion request to the branch's approvers.

Reject

Marks the promotion as rejected. The table definitions remain unchanged on the target branch.

Abandon

Discards the promotion entirely, typically when the changes are no longer needed.

The Promotions Page

Development > Promotions has a tab for each shared branch that promotions target — for example main and test. Each tab lists the promotions into that branch, and a count shows how many are waiting. The All tab lists every promotion.

Who Can Approve?

Promotion approval requires the approve permission on the target branch, granted through the "Branch [Name] Approver" user group.

Action	Who Can Do It
Create a promotion	Developers on the source branch
Promote / Reject / Retry	Approvers of the target branch, or Account Administrators
Edit pull request, Send request, Cancel, Abandon	The creator, developers on the source branch, approvers of the target branch, or Account Administrators

Typical Workflows

One shared branch (main)

Developer changes table definitions on their dev branch
  → Deploys to their Dev environment and tests
    → Promotes dev → main (approver reviews and approves)
      → Deployments are created for Stage and Prod
        → Deploy to Stage, test
          → Deploy to Prod

Test and main branches

Developer promotes dev → test   → a deployment is created for Test
Approver promotes test → main   → deployments are created for Stage and Prod

What Gets Promoted

A promotion copies the following from the source branch to the target branch:

Table definitions — the table metadata (name, domain, load type, description, etc.)
Column definitions — all columns with their types, constraints, and properties
Import mappings — reusable import definitions and their column mappings

A promotion does not copy data, and it does not change any environment until you deploy the deployments it creates.

Deployments — applying promoted definitions to environments
Branches — the branches between which you promote
Environments — where promoted changes are deployed
Permissions — how approver permissions work