Promoting Changes

Available to: Developers, Admins Minimum plan: Business

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., Development → Test → Production), with a review and approval step at each level. For the conceptual overview, see Promotions.

---

Prerequisites

• Business or Enterprise plan (promotions require multiple branches)
• At least one table definition on your current branch that has not yet been promoted (marked has_been_promoted = false)
• Editor or Developer permission on the source branch
• A parent branch must exist (you cannot promote from the top-level Production branch)

---

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. Click Create Promotion

---

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 cloned 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 has_been_promoted = true (they disappear from the unpromoted list)

Important: Deployment Is Still Required

Promoting does not change the physical database on the target branch. After promotion:

1. Switch to the target branch
2. Navigate to Development > Deployments
3. The promoted table definitions appear as requiring deployment
4. Create a new deployment and deploy them

---

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

The promotions index page at Development > Promotions shows all promotions:

• Filtered by default based on your current branch:
  • Private branch → filters by from-branch (shows your outgoing promotions)
  • Shared branch → filters by to-branch (shows incoming promotions for review)
• Filter by from-branch, to-branch, status, creator, or approver
• Sort by from-branch, to-branch, status, created date, or promoted date
• Paginated (12 per page)

---

Typical Workflows

Standard: Dev → Test → Prod

1. Edit table definitions on Development
2. Deploy on Development (test locally)
3. Create promotion: Development → Test
4. Approver reviews and approves (Promote)
5. Switch to Test, deploy the promoted definitions
6. Validate on Test
7. Create promotion: Test → Production
8. Approver reviews and approves (Promote)
9. Switch to Production, deploy

Feature Branch: Private → Dev → Test → Prod

1. Create a private branch from Development
2. Clone table definitions from Development
3. Make changes on the private branch
4. Deploy on the private branch (test in isolation)
5. Create promotion: Private Branch → Development
6. Approver reviews and approves
7. Switch to Development, deploy
8. Continue with standard workflow above
9. Delete the private branch when done

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 on the target branch
• 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