Aha! provides a two-way integration with GitHub that allows product teams to send their planned work from Aha! to their team working in GitHub. Before configuring any integration for the first time, it is important to fully understand how to think about integrating Aha! with your development tool. For teams using Github.com, please see our Github.com integration instructions.
This integration supports sending the following Aha! records to GitHub:
- Master features
The above Aha! records can be mapped to the following GitHub records:
- Task lists
To set up an integration with GitHub, you need to be a Product Owner in Aha! for the product you wish to integrate. You will also need to have a GitHub account that has proper access to create/edit records in GitHub for the repository you plan to integrate with.
1. Navigate to Settings > Product and click Integrations + on the left side navigation bar. Select GitHub from the integrations 2.0 grouping.
2. This will launch the integration configuration wizard. The first step is to name your integration and optionally select a template if you have already created one. Click Save and continue.
3. Next, you will be prompted to authenticate. Aha! uses OAuth for authentication with GitHub Enterprise. Aha! requires an OAuth access token, which you create in your GitHub account that contains the repositories you want to link. If you are linking repositories for a team, you should generate this token using the team account.
To create the token:
- Log in to GitHub as a user with admin permissions on the account.
- Click Edit Your Profile.
- Select Settings.
- Select the Developer Settings tab.
- Choose New OAuth app.
- Enter a name (ex: "Aha! Integration") for the Application Name.
- In the Homepage URL, enter your Aha! account URL (ex: https://youraccountnamehere.aha.io)
- In the Callback URL, field enter: https://secure.aha.io/integrations/oauth2_callback
- Click Register Application.
Keep the GitHub tab open for the next step as you will need the Client ID and Secret available.
4. Go back to Aha! where you are configuring the integration and enter the Client ID and Client Secret values from your GitHub application that you just created into the corresponding fields. Click Save & Continue.
Now you will authenticate the integration with GitHub. If you use SSO to log in to GitHub, then you should first log in to GitHub in another tab of your browser. Do this using the same credentials that you want Aha! to use. Then come back to the Aha! tab and click the Authenticate button to continue.
5. After authenticating, you will be prompted to choose a repository to integrate with. The list of repositories is based on what your GitHub user has available to them. This setting cannot be changed once the integration is in use.
6. After selecting a repository, you will be prompted to choose which project in GitHub you wish to integrate with. Similar to the workspace selection, the list presents the projects that you have access to within the previously selected workspace.
7. This integration can be optionally configured to bidirectionally sync GitHub issue state, project columns, and labels with the status of an Aha! record. The selections below will determine the status mapping options available in the next step.
- Enable issue state allows you to map the status of Aha! records with the state (open/closed) of GitHub issues.
- Enable project columns allows you to map the status of Aha! records with GitHub project columns.
- Enable status labels allows you to map the status of Aha! records with GitHub labels. Choose the GitHub labels that you would like to map to record status.
After you've enabled the desired status sync options, you will then set the mappings between Aha! and Github in the next step.
8. The next step is configuring how Aha! records are mapped to your GitHub records. The default mappings are based on what is most widely used by our customers. However, you are free to remove the default mappings and add your own to map records together based on what makes sense for your team and how you work.
9. Within each record mapping section, you can also specify your field mappings. This is an advanced option within the configuration that allows you to customize how each field within the record is mapped between Aha! and GitHub — as well as what relationship links exist for those records.
The relationship links are important to consider because they establish the ability for records created in your development system to be automatically imported into Aha! in certain use cases.
10. Next, you need to define the way statuses are mapped from GitHub to Aha! Within the field mapping section for each Aha! record, there is a line for Status with a gear icon at the far right. Click the gear icon to open up the status mapping window.
11. When mapping statuses, you will be presented with your Aha! status workflow for the record type on the left and your integrated system status workflow on the right. You can drag and drop the statuses to create groupings and mappings.
12. With your records, field mappings and statuses defined, you can click Save and continue to move onto the last step in the workflow. The Enable step allows you to specify how updates from Aha! are sent to your development system. The default setting is: Automatically send outgoing changes, which means that any change made to an integrated record will send to GitHub automatically.
We recommend the Approve outgoing changes setting for teams that are unfamiliar with how the integration works. The approval step allows teams that are new to the integration to validate what is being sent to their development system, which can help prevent unintentional changes from going through.
13. Finally, test the integration by opening one of your features in Aha!, clicking the Send dropdown, and selecting Send to GitHub. You should see a link to the created GitHub record appear on the Aha! feature after a few seconds. This will let you easily click into GitHub to verify that everything was sent through correctly.
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 Hooks 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, Issue comments, Labels, Milestones, and Project cards.
- Finally, click Add webhook.