Integrate with GitHub Issues

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

When you have completed your product roadmap and feature planning in Aha! you can move features into 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 tools integrations are configured under Settings -> Product. You need to be a Product Owner in Aha! to set up this integration.

Capabilities

One Aha! product can be associated with one or many Github repositories. If the association is a one to many, you need to set up different integrations for product -> repository mapping. Be sure to rename your integrations by clicking on their name at the top of the integration page and specifying the repo 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 sub-set of features. This is done through the Actions menu using Send to Github Issues.

The status in Aha! can be sent to the Github issue that is created as a label.*

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 checklists are used, 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 Aha!'s Update Github menu item, the entire issue description will be overwritten, reseting 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 Actions menu 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.

* 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.

If sending 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!

Configuration

You need to be a Product Owner in Aha! to set up this integration.

Please carefully follow these instructions to ensure that the integration is properly configured.

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.

If you are using Github Enterprise enter your server URL. If you are not using Enterprise leave the URL field empty.

Click the Test connection button

After a short delay, you will be able to choose the repository the issues will be created in.

Choose whether or not you wish to send Aha! status to labels in Github.

Enable the integration.

Test the integration by going to one of your features in Aha! and using the Send to Github Issues item in the Actions menu 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.

To receive updates when an issue is changed on Github you have to setup a webhook for the Github repository.

In Aha!, copy the Webhook URL from the Github issues integration settings.

On Github, go to the settings page of the Github repository and click on the Webhooks & Services 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.

In the Github issues integration settings, you can choose to which Aha! status the "Open" or "Closed" state of an issue should map.