Aha! Roadmaps | Integrate with GitHub (version 1.0)

We have updated this integration to version 2.0! 2.0 integrations have all the same functionality of a 1.0 integration, plus expanded capabilities and support.

This two-way integration allows you to push your features and requirements from Aha! Roadmaps into GitHub as issues and get status updates back.

When you have completed your roadmap and feature planning on the Aha! Roadmaps 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 your team to set brilliant strategy and share visual roadmaps while engineering can continue to work in GitHub Issues.

All new Aha! Roadmaps integrations are now 2.0 integrations. If you are ready to update your integration from 1.0 to 2.0, please follow these steps. You can also learn more about the GitHub Enterprise 2.0 and GitHub.com 2.0 integrations.

All development tool integrations are configured under Settings ⚙️ Workspace Integrations. You workspace owner in Aha! Roadmaps to set up this integration.

Click any of the following links to skip ahead:

• Create the integration in Aha! Roadmaps

• Receive updates from GitHub

• Notes

Create the integration in Aha! Roadmaps

• 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 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! Roadmaps status to labels in GitHub.

  • Status updates flow back from GitHub Issues to Aha! Roadmaps if you've added the webhook.

  • If the integration sends labels, updates to the label on the GitHub Issue will update the Aha! Roadmaps status. Note: Using more than one label will not update the status in Aha! Roadmaps.

• Click the checkbox to Enable the integration.

• Test the integration by going to one of your features in Aha! Roadmaps and using the Send to GitHub Issues option in the Integrations 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.

Top

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.

1. In Aha! Roadmaps, copy the webhook URL from the GitHub issues integration settings.

2. In GitHub, go to the settings page of the GitHub repository and click on the Webhooks tab.

3. Add a new webhook.

4. Paste the webhook URL into the Payload URL field. Choose application/json as content type and leave the secret field blank.

5. Select Let me select individual events and then check only Issues.

6. Finally, click Add webhook.

7. Back in Aha! Roadmaps, navigate to your GitHub issues integration settings, then choose which Aha! Roadmaps status the Open or Closed state of an issue should map to.

Top

Notes

• One Aha! Roadmaps workspace can be associated with one or many GitHub repositories. If the association is one too many, you need to set up different integrations for workspace-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 Integrations dropdown next to the integrations field on the record you want to send and then selecting Send to GitHub Issues.

• The status in Aha! Roadmaps 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! Roadmaps will not be updated.

  • Each time the feature is updated in GitHub using the Aha! Roadmaps 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! Roadmaps 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! Roadmaps reference link for a feature or requirement are sent, but comments are not.

• Aha! Roadmaps 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 Integrations 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! Roadmaps. Likewise, if an attachment is deleted in Aha! Roadmaps the corresponding attachment in GitHub is not deleted.

Top