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 Gear 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
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 http://app.clubhouse.io/<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:
The system also supports sets of URLS, bracketed Story numbers, or a mix of the two.
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)
The branch details include a link to GitHub and a dialog with a history of commit pushes, pull request events, and merges.
Multiple Stories can be associated with a single branch and pushing to a branch with a different Story will not disassociate it from any Story it was previously associated with.
Changing Your Workflow State Using GitHub Event Handlers
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.
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 http://app.clubhouse.io/<MYORG>/story/<story number>/<story-name> to a new pull request comment within GitHub:
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.
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:
Working with Individual Commits
For smaller Stories like hot fixes, you can associate an individual commit with the Story. Typically, these commits are pushed directly into “Master” or on to an intermediary branch like “Develop”. The mechanism for doing so is similar to associating a feature branch. You can simply use the Story URL http://app.clubhouse.io/<MYORG>/story/<story number>/<story-name> or bracketed text [ch###] where “###” is the Story ID anywhere within the commit message.
You can also do this in the GitHub UI by selecting "Create a new branch from this commit and start a pull request" and then pasting the branch information there as shown below).
Changing Your Workflow State with GitHub Commit Messages
It is also possible to change the workflow state of a Story via additional bracketed text commands within a commit message. To move the story to a "Finished" workflow state (as defined in your organization’s workflow), include your organization's designated finish verb in brackets in the last commit that you push (click here to read more about setting up and using verbs and workflow states in Clubhouse ).
Clubhouse will also add you as Owner to an unowned Story when GitHub activity is detected.
Disassociating Commits from a Clubhouse Story
Commits can be removed from Clubhouse Stories by clicking on the trash can icon next to the commit within the Story:
Reassociating Commits to a Clubhouse Story
Commits can be re-associated with Clubhouse Stories by clicking the "Restore" button next to the commit in the Story's Activity section:
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.