GitFlow Way-Of-Work

Created: March 8, 2026
Updated: October 30, 2026

Introduction

GitFlow separates day-to-day integration on develop from release preparation on release/* and production releases on master or main. For background, see the original branching model, GitVersion's GitFlow examples, and Semantic Versioning.

• Do not commit directly to the protected primary or support branches.
• Develop features on short-lived feature/* branches and merge them into develop through reviewed pull requests.
• Promote a tested release/* branch separately; creating a staging candidate is not a production release.
• Check the repository's CI and release policy before creating tags. Where CI owns publication, do not also tag or publish locally.

Configuration and deployment stages

The repository's .cloudopsworks/gitversion.yaml must have one # Agents: WayOfWork=GitFlow selector and a develop branch definition. Deployment mapping is configured under cd.deployments in .cloudopsworks/cloudopsworks-ci.yaml:

Actual environment names and whether deployment is enabled depend on that repository's configuration. A successful branch push does not by itself prove that a deployment completed. Preview environments may be created for feature or hotfix pull requests when configured.

Prerequisites and one-time initialization

Start with a Cloud Ops Works application template, or install Tronador CLI and provide the checked-in GitVersion presets and CI/CD configuration in your own repository. The CLI replaces the legacy Makefile bootstrap. Authenticate GitHub CLI (gh) for PR operations.

From a clean, synchronized primary branch, preview and select GitFlow:

tronador versions init --gitflow --dry-run
tronador versions init --gitflow

Initialization installs the GitVersion preset and creates/publishes develop when needed. It is a one-time setup, not a step to repeat for every release. Verify the active WayOfWork selector before using branch commands.

Feature branches

The CLI starts GitFlow features from develop:

tronador versions feature start <feature-name>
# Commit the change, including the +semver: annotation required by your GitVersion policy.
tronador versions feature publish
tronador versions feature finish

feature publish <feature-name> can publish a named branch from another checkout. feature finish opens a guarded pull request into develop; it does not merge the PR or delete the source branch. Wait for required checks and review, then merge under repository policy. A separate release-branch workflow owns promotion to the primary branch.

Only after confirming integration and remote state, purge an unneeded branch with tronador versions feature purge <feature-name> --allow-network. Purge is destructive and cannot replace a missing merge.

Release candidates and staging

Merge all intended changes into develop first, synchronize it with origin, and ensure the worktree is clean. GitVersion determines the next version from the configured commit patterns and history; the CLI does not accept a manual version, --major, or --minor on release start.

tronador versions release start --dry-run
tronador versions release start
tronador versions release publish

This creates and pushes release/vX.Y.Z. In a configured pipeline, the release/* push starts the test build/deployment (often staging). Watch that exact CI run and verify the deployment in the target environment. Release-specific fixes can be committed and republished to the same branch. Stop here for staging-only delivery; do not run release finish or create a production tag until the candidate is approved for promotion.

After staging validation, tronador versions release finish opens guarded promotion PRs for the primary branch and develop. It does not automatically merge, tag, or delete the branch. tronador versions release finish --local is a separate, publication-capable path and is appropriate only when repository policy explicitly assigns local release ownership. After both integration paths are verified and CI no longer needs the branch, tronador versions release purge vX.Y.Z --allow-network can remove it.

Pre-release and alternate-target tags

If the repository assigns tagging to an operator rather than CI, tronador versions tag --publish creates or publishes the GitVersion-calculated tag at the current commit. On develop it has an -alpha.N pre-release component; on release/* it has -beta.N. An optional positional qualifier selects a configured deployment target:

tronador versions tag --publish
tronador versions tag target1 --publish

The second command adds +deploy-target1 to the calculated version. Use it only when the corresponding cd.deployments.<stage>.targets.target1 exists. On a primary-branch release commit, it can select an alternate production target; it is not a staging-only action. Do not duplicate CI-owned tags or GitHub releases.

Hotfixes

For an urgent patch based on the primary branch:

tronador versions hotfix start
# Commit the fix and its configured semver annotation.
tronador versions hotfix publish
tronador versions hotfix finish

GitVersion calculates the patch branch name. The default finish opens a guarded PR into the primary branch; it does not merge or delete the source branch. GitFlow repositories must separately back-integrate the accepted fix into develop according to their release policy. Validate checks and any configured test deployment before promotion. Use tronador versions hotfix finish --local only when local publication is explicitly authorized. Tags on a hotfix branch follow the same CI-ownership rule described above.