Note: This article is intended for users who are maintaining a 1.0 integration. All new Aha! integrations are now 2.0 integrations. For those instructions, please see this article for GitHub Enterprise 2.0 and this article for GitHub.com 2.0.
This two-way integration allows you to push your features and requirements from Aha! into GitHub as issues and get status updates back.
When you have completed your product roadmap and feature planning on the Aha! side, you can move features into GitHub Issues for the engineering team to work on. You can send them individually or in bulk for a sprint or release. This makes it easy for product management to set brilliant product strategy and share visual roadmaps while engineering can continue to work in GitHub Issues.
All development tool integrations are configured under Settings > Product > Integrations. You need to be a product owner or administrator in Aha! to set up this integration.
Create the integration in Aha!
- Enter your GitHub username and click the Edit password link to enter your password or your GitHub Personal Token. A token is essential if you use two-factor authentication with your GitHub account. We recommend the use of a Personal Token.
Note: We recommend using unique credentials wherever possible, as GitHub limits the number of tokens available for each implementation. This is also advisable for account security purposes.
- If you are using GitHub Enterprise, enter your server URL. If you are not using GitHub Enterprise, leave the URL field empty.
- Click the Test connection button.
- After a short delay, you will be able to choose the repository that the issues will be created in.
- Choose whether or not you wish to send Aha! status to labels in GitHub.
- Status updates flow back from GitHub Issues to Aha! if you've added the webhook.
- If the integration sends labels, updates to the label on the GitHub Issue will update the Aha! status. Note: Using more than one label will not update the status in Aha!
- Click the checkbox to Enable the integration.
- Test the integration by going to one of your features in Aha! and using the Send to GitHub Issues option in the Send dropdown on the features page. You should then look at your repository in GitHub and see that the feature (and any requirements) were properly copied to issues.
Receive updates from GitHub
To receive updates when an issue is changed in GitHub, you have to set up a webhook for the GitHub repository.
- In Aha!, copy the webhook URL from the GitHub issues integration settings.
- In GitHub, go to the settings page of the GitHub repository and click on the Webhooks tab.
- Add a new webhook.
- Paste the webhook URL into the Payload URL field. Choose application/json as content type and leave the secret field blank.
- Select Let me select individual events and then check only Issues.
- Finally, click Add webhook.
- Back in Aha!, navigate to your GitHub issues integration settings, then choose which Aha! status the "Open" or "Closed" state of an issue should map to.
- One Aha! product can be associated with one or many GitHub repositories. If the association is one too many, you need to set up different integrations for product-repository mapping. Note: Be sure to rename your integrations by clicking on their name at the top of the integration page and specifying the repository you are sending the features to.
- Features can be sent to GitHub either by sending the entire release, one feature at a time, or bulk sending a subset of features. This is done through the Send dropdown next to the integrations field on the record you want to send and then selecting Send to GitHub Issues.
- The status in Aha! can be sent to the GitHub issue that is created as a label.
- Note: To create the statuses in GitHub, they must match the format of "Aha!:Status name." Always include the "Aha!:" before the status in GitHub.
- Sending a feature creates a GitHub issue.
- There are two ways to map requirements to issues: as stand-alone issues or as a markdown checklist within the main issue. If you use checklists, note that there are some significant caveats:
- When checklist items are ticked, the status of the corresponding requirement in Aha! will not be updated.
- Each time the feature is updated in GitHub using the Aha! Update GitHub menu item, the entire issue description will be overwritten, resetting the status of any checklist items that are already complete.
- Tags from the feature will be inherited in the resulting GitHub checklist. At that point, no tag updates will come from Aha! for requirements. Only the description of a feature or requirement is sent. No tasks or comments are included.
- The name, description, attachments, tags, and Aha! reference link for a feature or requirement are sent, but comments are not.
- Aha! releases will be created as milestones in GitHub.
- After a feature is first sent to GitHub, changes to the name, description, and requirements can also be sent to GitHub using the Update GitHub item in the Send dropdown on the features page or by sending all features in a release to GitHub again. New requirements will also be created in GitHub; however, issues that were created for an existing requirement are not deleted from GitHub if the requirement is deleted from Aha! Likewise, if an attachment is deleted in Aha! the corresponding attachment in GitHub is not deleted.