Branching Model

The sync module maps Git branches to CPI tenant environments.

Environment branches

Environment branches represent CPI environments:

Branch	Tenant
dev	DEV
qas	QAS
prd	PRD

The qas branch is only meaningful in a 3-tenant model.

Work branches

Work branches are any non-environment branches such as:

feature/new-flow
fix/email-routing
experiment/package-cleanup

Work branches map to DEV for push operations.

Recommended 3-tenant workflow

# Feature work
 git checkout -b feature/new-flow
# edit IntegrationPackage files
iflowkit sync push --message "WIP new flow"

# After PR/merge to dev
 git checkout dev
iflowkit sync push

# Promote DEV -> QAS
iflowkit sync deliver --to qas

# Promote QAS -> PRD
iflowkit sync deliver --to prd

Recommended 2-tenant workflow

# Work on dev
 git checkout dev
iflowkit sync push

# Promote DEV -> PRD
iflowkit sync deliver --to prd

What deliver does

deliver is not just a Git merge. It combines branch promotion with target tenant update and transport record creation.

At a high level it:

1. Determines the source and target branches.
2. Checks working tree cleanliness.
3. Verifies target branch and target tenant state.
4. Bootstraps missing environment branches from the tenant if necessary.
5. Merges source into target.
6. Applies the changed IntegrationPackage artifacts to the target tenant.
7. Writes transport records and tags the successful promotion.

Safety principles

• Keep environment branches protected where possible.
• Use pull requests for work branch → dev changes.
• Require --to prd for production operations.
• Review sync compare output before promotion.
• Do not manually edit transport records unless recovering from an exceptional situation.