GitHubFlow Examples

These examples are illustrating the usage of the supported GitHubFlow workflow in GitVersion. To enable this workflow, the builtin template GitHubFlow/v1 needs to be referenced in the configuration as follows:

workflow: GitHubFlow/v1
calculation:
  mode: ContinuousDelivery

Where the continuous deployment mode for no branches, the continuous delivery mode for main branch and the manual deployment mode for release, feature and unknown branches are specified.

This configuration allows you to publish CI (Continuous Integration) builds from main branch to an artifact repository. All other branches are manually published. Read more about this at version increments.

The continuous delivery mode has been used for the main branch in this examples (specified as a fallback on the root configuration layer) to illustrate how the version increments are applied. In production context the continuous deployment mode might be a better option when e.g. the release process is automated or the commits are tagged by the pipeline automatically.

Feature Branch

Feature branches can be used in the GitHubFlow workflow to implement a feature or fix a bug in an isolated environment. Feature branches will take the feature branch name and use that as the pre-release label. Feature branches will be created from a main or release branch.

Create feature branch from main

sequenceDiagram
    activate main
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    create participant feature as feature/foo
    main->>feature: branch from main
    activate feature
    deactivate main
    rect rgb(211, 211, 211)
        Note over feature: 1.2.1-foo.1+0
    end
    feature->>feature: commit
    rect rgb(211, 211, 211)
        Note over feature: 1.2.1-foo.1+1
    end
    activate main
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.1-1
    end
    main->>main: tag 1.2.1
    rect rgb(211, 211, 211)
        Note over main: 1.2.1
    end
    main->>feature: merge
    deactivate main
    rect rgb(211, 211, 211)
        Note over feature: 1.2.2-foo.1+2
    end
    feature->>feature: Commit '+semver: minor'
    rect rgb(211, 211, 211)
        Note over feature: 1.3.0-foo.1+3
    end
    feature->>feature: tag 2.0.0-foo.1
    rect rgb(211, 211, 211)
        Note over feature: 2.0.0-foo.2+0
    end
    feature->>feature: commit
    rect rgb(211, 211, 211)
        Note over feature: 2.0.0-foo.2+1
    end
    create participant pull as pull/2/merge
    main->>pull: branch from main
    activate pull
    feature->>pull: merge
    rect rgb(211, 211, 211)
        Note over pull: 2.0.0-PullRequest2.5
    end
    destroy pull
    main--xpull: delete branch
    feature->>main: merge
    Note over feature: Feature branches should
be deleted once merged destroy feature main--xfeature: delete branch rect rgb(211, 211, 211) Note over main: 2.0.0-5 end activate main main->>main: commit rect rgb(211, 211, 211) Note over main: 2.0.0-6 end main->>main: tag 2.0.0 rect rgb(211, 211, 211) Note over main: 2.0.0 end

After the feature branch is merged, the version on main is 2.0.0-5. This is due to main running in continuous delivery mode. If main was configured to use continuous deployment the version would be 2.0.0.

Mainline version strategy comparison

The same feature branch history produces different versions when the Mainline version strategy is used. In particular, the final untagged commit on main becomes 2.0.1-1 rather than 2.0.0-6:

sequenceDiagram
    activate main
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.0-1
    end
    create participant feature as feature/foo
    main->>feature: branch from main
    activate feature
    deactivate main
    rect rgb(211, 211, 211)
        Note over feature: 1.2.1-foo.1+0
    end
    feature->>feature: commit
    rect rgb(211, 211, 211)
        Note over feature: 1.2.1-foo.1+1
    end
    activate main
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.1-1
    end
    main->>feature: merge
    deactivate main
    rect rgb(211, 211, 211)
        Note over feature: 1.2.2-foo.1+2
    end
    feature->>feature: Commit '+semver: minor'
    rect rgb(211, 211, 211)
        Note over feature: 1.3.0-foo.1+3
    end
    feature->>feature: tag 2.0.0-foo.1
    rect rgb(211, 211, 211)
        Note over feature: 2.0.0-foo.2+0
    end
    feature->>feature: commit
    rect rgb(211, 211, 211)
        Note over feature: 2.0.0-foo.2+1
    end
    create participant pull as pull/2/merge
    main->>pull: branch from main
    activate pull
    feature->>pull: merge
    rect rgb(211, 211, 211)
        Note over pull: 2.0.0-PullRequest2.5
    end
    destroy pull
    main--xpull: delete branch
    feature->>main: merge
    Note over feature: Feature branches should
be deleted once merged destroy feature main--xfeature: delete branch rect rgb(211, 211, 211) Note over main: 2.0.0-5 end activate main main->>main: commit rect rgb(211, 211, 211) Note over main: 2.0.1-1 end

The other Mainline integration scenarios use the same branch histories as the release examples below, so they are not repeated here. See DocumentationSamplesForGitHubFlow.cs for the complete executable scenarios and their expected versions.

Release Branches

Release branches are used for major, minor and patch releases to stabilize a RC (Release Candidate) or to integrate features/hotfixes (in parallel) targeting different iterations. Release branches are taken from main and will be merged back afterwards. Finally the main branch is tagged with the released version.

Release branches can be used in the GitHubFlow as well as GitFlow workflow. Sometimes you want to start on a large feature which may take a while to stabilize so you want to keep it off main. In these scenarios you can either create a long lived feature branch (if you do not know the version number this large feature will go into, and it's non-breaking) otherwise you can create a release branch for the next major version. You can then submit pull requests to the long lived feature branch or the release branch.

Create release branch

sequenceDiagram
    activate main
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    create participant release as release/next
    main->>release: branch from main
    activate release
    deactivate main
    rect rgb(211, 211, 211)
        Note over release: 1.2.1-beta.1+0
    end
    release->>release: commit
    rect rgb(211, 211, 211)
        Note over release: 1.2.1-beta.1+1
    end
    activate main
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.1-1
    end
    main->>main: tag 1.2.1
    rect rgb(211, 211, 211)
        Note over main: 1.2.1
    end
    main->>release: merge
    deactivate main
    rect rgb(211, 211, 211)
        Note over release: 1.2.2-beta.1+2
    end
    release->>release: Commit '+semver: minor'
    rect rgb(211, 211, 211)
        Note over release: 1.3.0-beta.1+3
    end
    release->>release: tag 1.3.1-beta.1
    rect rgb(211, 211, 211)
        Note over release: 1.3.1-beta.2+0
    end
    release->>release: commit
    rect rgb(211, 211, 211)
        Note over release: 1.3.1-beta.2+1
    end
    create participant pull as pull/2/merge
    main->>pull: branch from main
    activate pull
    release->>pull: merge
    rect rgb(211, 211, 211)
        Note over pull: 1.3.1-PullRequest2.5
    end
    destroy pull
    main--xpull: delete branch
    release->>main: merge
    Note over release: Release branches should
be deleted once merged destroy release main--xrelease: delete branch rect rgb(211, 211, 211) Note over main: 1.3.1-5 end activate main main->>main: commit rect rgb(211, 211, 211) Note over main: 1.3.1-6 end main->>main: tag 1.3.1 rect rgb(211, 211, 211) Note over main: 1.3.1 end

Create release branch with version

sequenceDiagram
    activate main
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    create participant release as release/2.2.1
    main->>release: branch from main
    activate release
    deactivate main
    rect rgb(211, 211, 211)
        Note over release: 2.2.1-beta.1+0
    end
    release->>release: commit
    rect rgb(211, 211, 211)
        Note over release: 2.2.1-beta.1+1
    end
    activate main
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.1-1
    end
    main->>main: tag 2.2.1
    rect rgb(211, 211, 211)
        Note over main: 2.2.1
    end
    main->>release: merge
    deactivate main
    rect rgb(211, 211, 211)
        Note over release: 2.2.2-beta.1+2
    end
    release->>release: Commit '+semver: minor'
    rect rgb(211, 211, 211)
        Note over release: 2.3.0-beta.1+3
    end
    release->>release: tag 2.3.1-beta.1
    rect rgb(211, 211, 211)
        Note over release: 2.3.1-beta.2+0
    end
    release->>release: commit
    rect rgb(211, 211, 211)
        Note over release: 2.3.1-beta.2+1
    end
    create participant pull as pull/2/merge
    main->>pull: branch from main
    activate pull
    release->>pull: merge
    rect rgb(211, 211, 211)
        Note over pull: 2.3.1-PullRequest2.5
    end
    destroy pull
    main--xpull: delete branch
    release->>main: merge
    Note over release: Release branches should
be deleted once merged destroy release main--xrelease: delete branch rect rgb(211, 211, 211) Note over main: 2.3.1-5 end activate main main->>main: commit rect rgb(211, 211, 211) Note over main: 2.3.1-6 end main->>main: tag 2.3.1 rect rgb(211, 211, 211) Note over main: 2.3.1 end

To Contribute

See contributing examples.

Source

The diagrams are generated from DocumentationSamplesForGitHubFlow.cs. After changing a scenario, run the GenerateMermaidSources Cake task, inspect the updated Mermaid source, and run the ValidateMermaidDiagrams Cake task before committing it.