Aha! Roadmaps | Integrate with GitHub Enterprise

Aha! Roadmaps provides a two-way integration with GitHub Enterprise that allows teams to send their planned work from Aha! Roadmaps 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! Roadmaps with your development tool.

For teams using Github, please see our Github integration instructions.

Click any of the following links to skip ahead:

• Prerequisites

• Configure the integration

  • In Aha! Roadmaps

  • In GitHub Enterprise

  • Back in Aha! Roadmaps

• Configure mappings

• Enable the integration

• Test the integration

• Add additional security

• Receive updates

Prerequisites

Top

Configure the integration

Navigate to Settings ⚙️ Workspace Integrations and click the + on the left side navigation bar. Select GitHub Enterprise from the integrations 2.0 grouping.This will launch the integration configuration wizard.

In Aha! Roadmaps

1. Start: The first step is to name your integration and optionally select a template if you have already created one. Click Save and continue.

2. Authenticate: Next, you will be prompted to authenticate. Aha! Roadmaps uses OAuth 2.0 for authentication, and if you are already logged into an active GitHub Enterprise session in your browser, you will not be prompted for credentials and instead you will be prompted by GitHub Enterprise to grant Aha! Roadmaps access. If you are not currently logged into GitHub Enterprise, you will be prompted with an GitHub Enterprise authentication screen.

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.

In GitHub Enterprise

To create the token:

1. Log in to GitHub Enterprise as a user with admin permissions on the account.

2. Click Edit Your Profile.

3. Select Settings.

4. Select the Developer Settings tab.

5. Choose New OAuth app.

6. Enter a name (ex: "Aha! Roadmaps Integration") for the Application Name.

7. In the Homepage URL, enter your Aha! Roadmaps account URL (ex: https://youraccountnamehere.aha.io)

8. In the Callback URL, field enter: https://secure.aha.io/integrations/oauth2_callback

9. Click Register Application.

Keep the GitHub tab open for the next step as you will need the Client ID and Secret available.

Back in Aha! Roadmaps

1. Go back to Aha! Roadmaps 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 Enterprise. 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! Roadmaps to use. Then come back to the Aha! Roadmaps tab and click the Authenticate button to continue.

2. Organization: If you want to map to GitHub project status and custom fields, select an Organization in this step. This setting cannot be changed once the integration is in use.

3. Repository: 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.

4. Options: This integration can be optionally configured to bi-directionally sync GitHub issue state, project columns, and labels with the status of an Aha! Roadmaps record. The selections below will determine the status mapping options available in the next step.

   1. Project: Choose a GitHub project to integrate with your workspace. This selection enables you to map the status of Aha! Roadmaps records with the state (open/closed) of GitHub issues.

   2. Issue state: Choose to enable or disable GitHub issue state mappings. The actual mapping will happen in the next step of the integration configuration.

   3. Statue labels: Choose to enable to disable GitHub status mappings. When enabled, you can map Aha! Roadmaps record statuses with GitHub status labels. The actual mapping will happen in the next step of the integration configuration, but use the Status dropdown here to select the GitHub labels that you would like see as options in the Mappings step.

Top

Configure mappings

The next step is configuring how Aha! Roadmaps 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.

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! Roadmaps and GitHub Enterprise — as well as what relationship links exist for those records. If you selected an Organization during the initial integration configuration, you can also map to GitHub custom fields.

If you have configured required fields in GitHub Enterprise, we recommend setting the Required flag on those fields in the custom layout associated to your workspace. This will ensure that any required fields are populated when records are created on the Aha! Roadmaps record creation form.

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! Roadmaps in certain use cases.

Top

Enable the integration

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 covers two last items.

First, the Webhook URL. If you set any mappings to sync from GitHub to Aha!, you will need to set up a webhook in GitHub so that Aha! can receive updates — and how you enable that webhook depends on whether you use GitHub organizations.

Second, specify how updates from Aha! Roadmaps are sent to your development system. The default setting is to 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.

If a feature's parent release is not linked with Aha! Roadmaps, or if releases are not mapped with the development system at all, then the feature will be imported into the first parking lot release. This is by design, since the parking lots are repositories for unscheduled work.

Top

Test the integration

Congratulations! You're ready to test your new integration. To do this, send a feature to Github by following these steps:

1. Navigate to Features Board.

2. Open one of your features in Aha! Roadmaps, scroll to the Integrations field, and select Send to Github.

You should see a link to the created Github record appear on the Aha! Roadmaps feature after a few seconds. This will let you easily click into Github to verify that everything was sent through correctly.

You also have the ability to bulk send a subset of features to GitHub.

Top

Add additional security

2.0 integrations have the option to include a client certificate for added integration security.

To set a client certificate, open your integration settings and click the More options icon in the upper right, then click Set client certificate. From here, enter the private key and certificate — we recommend creating a private key and client certificate specifically for this purpose — and click Save to save your changes.

If you use an integration template to manage multiple integrations in the same workspace, set the client certificate in your integration template. That way, you only need to set the client certificate once.

Note: This feature will only provide additional security when the server that Aha! Roadmaps is communicating with validates the certificate. This is usually only possible with customer-configured on-premises integrations. Client certificate authentication is in addition to the standard username and password/token authentication and is not a replacement.

Top

Receive updates

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 Hooks 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, Issue comments, Labels, Milestones, and Project cards.

6. Finally, click Add webhook.

Top