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.

The Git Helpers menu

 Clubhouse GitHelpers Menu

Associating Branches without Clubhouse Git Helpers

If you don't use our naming convention to create your branch, you can also associate a branch by including the URL<MYORG>/story/<Story Number>/<story-name> or this bracketed text anywhere within a commit message: [branch ch###] where “###” is the Story ID. The keyword “branch” will associate the Story to the feature branch. 

This example associates story id 1234:

Clubhouse Git Commit Example

The system also supports sets of URLS, bracketed Story numbers, or a mix of the two.

Clubhouse Git Commit

After the association, Clubhouse will add you as Owner, move the Story to a “Started” workflow state if it’s not there already (click here to read more about Workflow states in Clubhouse), and add branch details to the Story dialog.

Clicking on the list icon in the linked Pull Request information area will give you more information on branch activity. (See image below)

Github commit changes

The branch details include a link to GitHub and a dialog with a history of commit pushes, pull request events, and merges.  

Associating Multiple Stories with a Single Branch via 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

Enabling Github Event Handlers in Clubhouse

You can use the Clubhouse GitHub Event Handler to allow GitHub events to trigger workflow state changes. Instructions for setup are here

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.

Pull Requests in Clubhouse

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<MYORG>/story/<story number>/<story-name> to a new pull request comment within GitHub:

Pull Request Comment in Clubhouse

Please note this bracketed text [ch###] or Story URL must be added as a PR comment. Adding the Story reference to the PR description 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 work properly.

Pull Request Comment Github Clubhouse

Linking GitHub pull request to Clubhouse Stories


Disassociating Pull Requests From A Clubhouse Story

Pull requests can be removed from Clubhouse Stories by clicking on the trash can icon next to the pull request within the Story:



Pull requests can be reassociated with Clubhouse Stories by clicking the "Restore" button next to the pull request in the Story's Activity section:

Restore Pull Request Clubhouse

Moving Stories Back

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

Have more questions? Submit a request


  • Avatar

    Looks great. But for us, no Bitbucket integration stops the show. You guys mentioned (here) that this is in the works. Any release date yet? Can we Beta test it? Would love to help out. ^WG

    Edited by Peakfijn
  • Avatar

    If there is anything we can do to help with the Bitbucket integration please let us know, cheers!

  • Avatar
    Tord Jansson

    For my workflow, branching for every story is not a good solution. Can't I just use keywords in my commits instead, like [open #123], [fix #123] etc?

    The reason I don't want to branch for every story is that I'm a lone developer and it's better for me to stay on the edge all the time and not divide my work into 4-5 different branches just because I've made partial work on several stories that don't break anything. That would feel schizophrenic. I only branch if a story is experimental or otherwise risk to break things.

  • Avatar
    Tibi Stibi

    +1 Tord Jansson

  • Avatar

    We're considering moving to Pipefy instead, as those guys do integrate with Bitbucket.

    Edited by Peakfijn
  • Avatar
    Jacob Thomason

    Interesting Peakfijn, Pipefy looks pretty good, we'll have to check that out. It doesn't seem like Clubhouse has much motivation to get Bitbucket integration in place.

Article is closed for comments.
Powered by Zendesk