GitHub Flow Way-Of-Work

Created: April 17, 2026
Updated: October 30, 2026

Introduction

GitHub Flow uses one long-lived primary branch (master or main) and short-lived branches merged through pull requests. See GitHub Flow, Semantic Versioning, and GitVersion's increment strategy for background.

Do not commit directly to the protected primary branch.
Start feature and hotfix branches from the primary branch; there is no develop branch.
Include the appropriate +semver: annotation in commits and the PR body when the repository's GitVersion policy requires it.
Most GitHub Flow releases need no release branch; merging to primary and CI-owned tagging can complete the release. An optional release branch is a repository-specific choice, not a prerequisite.

Configuration and deployment stages

Use a single active .cloudopsworks/gitversion.yaml with one # Agents: WayOfWork=GitHubFlow selector. Check the actual major-version-bump-message, minor-version-bump-message, patch-version-bump-message, and no-bump-message patterns before selecting annotations. Aliases such as +semver: breaking are not portable: different repositories can map them to different version levels.

The cd.deployments section of .cloudopsworks/cloudopsworks-ci.yaml maps primary-branch release tags to the release target. Pull requests can create previews when configured. A hotfix push does not universally deploy to test; confirm the repository's workflow triggers and deployment configuration rather than assuming it does. A tag or push is not evidence that deployment succeeded.

Common annotation	Intended effect
`+semver: major`	Major increment
`+semver: minor`	Minor increment
`+semver: patch`	Patch increment
`+semver: none`	No requested increment

Use only annotations matched by the repository's active GitVersion configuration. For example:

feat: add user authentication +semver: minor
fix: resolve login error +semver: patch
chore: refresh documentation +semver: none

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 GitHub Flow:

tronador versions init --githubflow --dry-run
tronador versions init --githubflow

Initialization installs the GitVersion preset but does not create develop. Run it once when choosing the workflow, not before each feature. Verify the active WayOfWork selector and align config.gitFlow.enabled in .cloudopsworks/cloudopsworks-ci.yaml with the selected flow before branch operations.

Feature branches

The CLI uses the configured primary branch as the feature base in GitHub Flow:

tronador versions feature start <feature-name>
# Commit the change with the configured +semver: annotation.
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 PR into the primary branch; it does not merge the PR or delete the branch. Wait for required checks and review, merge according to repository policy, and observe CI-owned release automation. Only after verifying integration and remote state should you run tronador versions feature purge <feature-name> --allow-network.

Hotfixes

If the repository uses hotfix/* branches, the CLI can calculate the next patch branch from primary:

tronador versions hotfix start
# Commit the fix with the configured patch annotation.
tronador versions hotfix publish
tronador versions hotfix finish

The default finish opens a guarded PR into the primary branch rather than merging or deleting it. Validate checks, preview/deployment results, and CI release ownership before promotion. tronador versions hotfix finish --local is publication-capable and should only be used where repository policy explicitly assigns publication to the operator.

Tags and alternate deployment targets

Where CI owns release tagging or publication, observe its workflow instead of creating a competing tag or GitHub release. Only in an operator-owned release workflow, on the intended commit, use:

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

The CLI calculates the version with GitVersion; the optional positional qualifier appends +deploy-target1 for a configured cd.deployments.release.targets.target1. --publish pushes the selected tag to origin. Confirm the resulting CI run and target deployment rather than treating the push as a completed release.