Promoting Changes

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

This guide walks through the step-by-step process of promoting table definition changes from one branch to another in TitanRDM. Promotions move definitions upward through the branch hierarchy (e.g., your development branch → main), with a review and approval step at each level. When a promotion completes, a deployment is created for every environment the target branch deploys to. For the conceptual overview, see Promotions.

---

Prerequisites

• Any plan — all plans include multiple branches and promotions
• Your current environment is deployed from the branch you want to promote (usually your own Dev environment)
• At least one table definition on that branch that has not yet been promoted
• Developer permission on the source branch
• The branch must have a parent branch (you cannot promote from the top-level branch, such as main)

---

Step 1: Select Table Definitions to Promote

There are two ways to start a promotion:

From the Promotions Page

1. Navigate to Development > Promotions
2. Click New Promotion
3. TitanRDM shows all unpromoted table definitions on your current branch

From the Table Definitions Page

1. Navigate to Development > Table Definitions
2. Select one or more tables using the checkboxes
3. Click Promote in the toolbar
4. You are redirected to the New Promotion page with your selections pre-checked

The Selection Grid

The New Promotion page shows:

You can filter by name or domain, and sort by name, domain, or selection status.

The from branch (source) is your current branch. The to branch (target) is automatically set to your current branch's parent.

1. Optionally enter a Description and a Pull Request: the pull request with the data platform code changes that go with these table changes. When the pull request is merged, your CI/CD pipeline can promote this promotion, then deploy it with each release. You can add or change the pull request later from the promotion page.
2. Click Create Promotion

Pull Request

Enter the repository and pull request number in the same format your CI/CD pipeline uses, for example my-org/data-platform#42 (GitHub) or data-platform#42 (Azure DevOps). Each pull request can belong to only one active promotion. See CI/CD Integration.

Leave it blank if you promote and deploy from TitanRDM yourself.

Once your pipeline has promoted the promotion, its page also shows the Merge Commit that merged the pull request.

---

Step 2: Review the Diff

After creation, you are taken to the promotion detail page. TitanRDM compares each selected table definition on the source branch against its counterpart (if any) on the target branch and displays a comprehensive diff.

Diff Categories

The diff is organised into multiple levels:

Each change shows old value (on the target branch) and new value (from the source branch) side by side.

---

Step 3: Request Approval or Approve

Depending on your permissions, you have different options:

If You Are an Approver on the Target Branch

You can act immediately:

If You Are Not an Approver

1. Click Send Request
2. Optionally add a comment explaining the changes
3. The promotion status changes to Requested
4. Approvers on the target branch receive an email notification with a link to the promotion

The approvers can then review the diff and approve, reject, or abandon.

---

Step 4: After Approval (Promote)

When a promotion is approved (status changes to Promoted):

1. Table definitions are copied from the source branch to the target branch
2. Column definitions, import mappings, and column mappings are all copied
3. Foreign key references are re-pointed to the equivalent tables on the target branch
4. The source table definitions are marked as promoted (they disappear from the unpromoted list)
5. A deployment is created for each environment the target branch deploys to — for example one for Stage and one for Prod when promoting into main

Deploying the Changes

Promoting does not change any environment by itself. The Deployments panel on the promotion page lists the deployments that were created, with a link to each:

1. Open the deployment for your non-production environment (e.g. Stage), review it, and click Deploy
2. Test the changes in that environment
3. Open the deployment for production and deploy it

See Deploying Changes.

---

Cancelling a Promotion

If you created a promotion but no longer want to proceed:

1. Open the promotion detail page
2. Click Cancel
3. Optionally add a comment
4. The status changes to Cancelled

Only the creator (or admin) can cancel a promotion that has not yet been approved.

---

Abandoning a Promotion

To abandon a promotion after it has been requested:

1. Open the promotion detail page
2. Click Abandon
3. Optionally add a comment
4. The status changes to Abandoned
5. Branch approvers are notified via email

---

Retrying a Failed Promotion

If a promotion fails (e.g., due to a missing foreign key reference on the target branch):

1. The status changes to Failed
2. The error message is displayed on the detail page
3. Fix the underlying issue (e.g., promote the referenced table first)
4. Click Retry to re-run the promotion

---

Promotion Actions (Audit Trail)

Every promotion maintains a complete audit trail:

Each action records the user, timestamp, and optional comment.

---

Promotions List

Development > Promotions has a tab per shared target branch (e.g. main, test), each listing the promotions into that branch, plus an All tab. It opens on the branch your current branch promotes into.

• Filter by from-branch, status, creator, or approver
• Sort by from-branch, status, created date, or promoted date
• The pull request of each promotion is shown under its number

---

Typical Workflows

One Shared Branch: dev → main

1. Clone table definitions from main into your development branch
2. Make changes and deploy them to your Dev environment
3. Create promotion: your branch → main
4. Approver reviews and promotes
5. Deployments are created for Stage and Prod
6. Deploy to Stage and validate
7. Deploy to Prod

With a Test Branch: dev → test → main

1. Promote your branch → test; deploy the Test deployment and validate
2. Promote test → main; deploy the Stage deployment, validate, then deploy Prod

Self-Approval

If you are both the creator and an approver on the target branch, you can approve your own promotions immediately without waiting. TitanRDM does not enforce a "four-eyes" principle — this is left to your organisation's policies.

---

Tips

• Promote related tables together — if Table A references Table B, include both in the same promotion to avoid missing reference errors
• Check the diff carefully — especially for column deletions, which will result in data loss when deployed to the target branch's environments
• Promote frequently — smaller promotions are easier to review and less likely to have conflicts
• Use the "from Table Definitions" workflow — selecting tables and clicking Promote is faster than starting from the Promotions page for common cases

---

Related Pages

• Promotions (Concept) — lifecycle and architecture overview
• Deploying Changes — the step after promotion
• Working with Branches — creating feature branches
• Cloning Tables — an alternative to promotion for copying definitions
• Permissions — approver permissions