Using the Clubhouse GitHub Integration with Branches and Pull Requests

The Clubhouse GitHub integration offers several ways to associate Clubhouse Stories with GitHub feature branches or commits, as well as automated ways to change the workflow state of a Story as your work progresses. 

Working with Feature Branches

A Story is often analogous to the amount of work in a feature branch. To create a new feature branch, click the Story you want to work with, and then click the "Git Helpers" icon located in between the Story ID number and Settings ellipsis icon.


Then copy the suggested branch name to create and checkout a new branch for your story. Whenever you push a branch, it will be automatically linked to the story.

Associating Multiple Stories with a Single Pull Request 

Branches can be associated with multiple stories using pull request messages. Just add the Story numbers to the message with the prefix `ch` in brackets.
Pull Request Comment Github Clubhouse
While multiple Stories can be associated with a single branch, pushing to a branch with a different Story number will not disassociate it from any Story it was previously associated with. See the section below on disassociating pull requests from Stories. 

Changing your Workflow State Using GitHub Event Handlers


You can use Clubhouse GitHub Event Handlers to allow GitHub events to trigger workflow state changes.

Opening a Pull Request from within Clubhouse

When a Story has a linked branch, you can open a new Pull Request from the Clubhouse UI by clicking the "Open PR" button next to the branch name. This will pre-fill the Story name in the PR name and the Story URL in the PR description.


Working with Pull Requests

When a Pull Request is opened on an already linked feature branch it will be indicated in the Stories associated with that feature branch.


It is also possible to associate a Story to a feature branch upon creation of a pull request or after a Pull Request has been opened.  

Add the bracketed text [ch###] where ### is the Story number, or the Story URL{org}/story/{story-id} to a new Pull Request comment in GitHub:

Pull Request Comment in Clubhouse

Please note this bracketed text or Story URL must be added as a comment on the Pull Request. Adding the Story reference to the Pull Request title is not supported.

The system supports sets of bracketed Story numbers on a Pull Request, but the Story URL needs to be the only text in the PR comment in order to be picked up.

Pull Request Comment Github Clubhouse

Linking GitHub pull request to Clubhouse Stories 

Prevent PR from moving a Story

To prevent a given PR from moving a story, do any of the following:

  • Add a label named skip-ch
  • Include the text [skip-ch] in the PR body
  • Include the text [skip-ch] in the PR title

Disassociating Pull Requests from a Clubhouse Story

Pull Requests can be removed from Clubhouse Stories by clicking on the ellipsis icon next to the pull request within the Story and clicking "Dissociate Pull Request from Story".

Moving Stories Back

The Clubhouse GitHub integration is designed to move your Stories forward, from unstarted to completed. As such, if you find you need to move a Story back to an earlier workflow state, you can do so in the Clubhouse UI.