Last month, we introduced GitHub integration to Matterhorn projects. However, we know this is a really important feature, and want to make it the best that it can possibly be. That’s why we’ve been hard at work to bring you an even better GitHub integration.
We’ve overhauled the way Matterhorn integrates with GitHub in order to allow you to:
- Manage all your project integrations in one place instead of on a project only level.
- Link multiple GitHub repos to one Matterhorn project
- Create and Close tickets through GitHub Issues
- Track comments from
Setting up your GitHub Integration
Matterhorn’s new GitHub integration uses oAuth tokens rather than webhooks.
The GitHub integration works on a company level. This means as soon as anyone authorises with their GitHub account, everyone in the team will be able to link Matterhorn projects to any repo accessible by that account. We recommend that the main account holder links their account.
To set up your GitHub Services, go to Configure Integrations under the Settings Tab.
Click on the Connect with GitHub button. This will bring up a popup asking you to confirm that you want to give Matterhorn permission to access your GitHub account.
Matterhorn requires full access in order for the issues integration to function. If you have any questions or concerns about this you can contact us.
Linking up your repositories
After giving Matterhorn access to your GitHub account, you can start linking your GitHub Repos with your Matterhorn Projects. If no projects are linked, you will be taken to the “quick link” screen. Here you will see a list of all your Matterhorn projects on the left, and dropdowns with your GitHub repositories on the right.
You can then select the repo you want to link to each project, as well as what events you want to listen to.
Matterhorn can listen to these events:
- Commits pushed to the repository
- New comment on commit
- Pull request opened or closed
- Issue opened, closed, assigned, or labeled
- New comment on issue or pull request
Unfortunately, event listeners cannot be configured after the service has been created. If you need to change these settings later on you will have to remove and recreate the service.
If there are Matterhorn projects you don’t need to link up, you can remove them from the quick link list by pressing the red cross. When you’re happy with your settings, press Create services.
Managing & Adding services
After setting up some initial services, you can always return to Configure Integrations to edit and add services.
From this screen, you can remove existing services or add a new service. To add a new service, select the Matterhorn Project and GitHub repo that you want to link up and press Create Service
Using the GitHub Integration
Setting up your account
When we connect to GitHub in this way, we only know who is creating or commenting on tickets by their GitHub username. Make sure to enter your GitHub username in My Profile (under the Settings Tab)
GitHub Commits and Matterhorn
As in the previous integration, you can reference tickets in your commits via their ticket id (by writing the full number including the hash eg #162).
- If you just leave a reference, this will be added as a comment to the ticket
- If you’re starting work on a ticket, you can move it to in progress by having the ticket id and any of these words in your commit message. breaks, unfixes, reopen, reopens, re-open, re-opens, open, opens
- If you’re starting work on a ticket, you can move it to complete by having any of these words in your commit message. close, closes, closed, fix, fixed, fixes
GitHub Issues and Matterhorn
Any issues you create in GitHub will now be added as a ticket in the linked Matterhorn project. These tickets are automatically grouped under the Feature GitHub Issues, to help you keep track of them. You can change the feature of a GitHub Issue ticket after creating it.
Commenting on a GitHub Issue will add a comment to its corresponding Matterhorn ticket.
Closing a GitHub Issue in GitHub will Close the issue in Matterhorn.