To avoid redundant third-party notifications, changes to the text editor are delayed by at least five minutes, waiting for five minutes after the most recent change.
Your development team brings your product strategy to life. You rely on them to help you build something great. They rely on you for strategic context and direction. If you are fortunate enough to work with a team of talented developers, you know how exciting it is to see each release bring lovable updates to your customers.
For many teams, it takes serious effort to keep both product managers and developers aligned. Both teams might use different terminology for the same work. Both prefer to use purpose-built tools designed for their use case. But product roadmaps are dynamic and development often happens quickly. You do not want to spend precious time doubling back to manually update the changes between different systems.
The Aha! Roadmaps integration with GitHub automates those manual updates, freeing product managers and developers to focus on building breakthrough products. Bidirectional updates mean that strategic context flows from Aha! Roadmaps into GitHub and development progress flows back to you in real time. You can map fields and record types to each other and collaborate with developers through comments without either team leaving their tool of choice.
The integration connects through the Aha! GitHub App. Compared with the earlier OAuth-based integration, the app gives you:
Automatic webhooks: The app manages webhooks for you, so you do not configure them for each repository.
Central administration: Manage the app from your GitHub organization settings. Add or remove repositories, approve or deny permission changes, and uninstall the app if you need to.
Stronger security: The integration makes updates as the app rather than as the person who set it up. You get clearer audit trails, finer-grained permissions, and short-lived access tokens.
Reliability: The integration keeps working if the person who configured it leaves your organization or loses access to the repository.
Higher rate limits: API rate limits scale with the size of your GitHub organization rather than with one person's limit.
IP allow lists: If you use GitHub Enterprise Cloud, add the Aha! IP addresses to your organization's IP allow list automatically.
If you set up a GitHub integration before the Aha! GitHub App was available, it keeps working without changes. Use the app for any new GitHub integration.
In this article, we will walk you through how to configure and customize your GitHub integration, including the option to add additional security through a client certificate.
Click any of the following links to skip ahead:
Prerequisites
Integration type |
|
Aha! Roadmaps level |
|
Required user permissions: |
|
Required user permissions: |
|
Associated record types |
Aha! Roadmaps
GitHub
|
Configuration
Navigate to User menu -> Settings -> Workspace -> Integrations and click the + on the left side navigation bar. Select GitHub App from the integrations 2.0 grouping. This will launch the integration configuration wizard.
Start: The first step is to name your integration and optionally select a template if you have already created one. Click Save and continue.
-
Account: Connect Aha! Roadmaps to GitHub through the Aha! GitHub App. Click Authenticate to sign in to GitHub. If you already have an active GitHub session in your browser, GitHub asks you to grant Aha! Roadmaps access. Otherwise, GitHub displays its sign-in screen. Then click Install to install the app in your GitHub organization. GitHub returns you to Aha! Roadmaps when the installation finishes.
You only install the app once per GitHub organization, and later integrations use the same installation. If the app is already installed, skip Install. You can also install the app directly from GitHub at https://github.com/apps/integrate-with-aha.
Note: You must be a GitHub organization owner to install the app.
If you use single sign-on (SSO) to log in to GitHub, first log in to GitHub in another browser tab with the same credentials you want Aha! Roadmaps to use. Then return to the Aha! Roadmaps tab and click Authenticate to continue.
Organization: If you want to map to GitHub project status and custom fields, select an Organization in this step. You cannot change this setting once you use the integration.
Repository: Choose a repository to integrate with. GitHub lists the repositories available to your user. You cannot change this setting once you use the integration.
-
Options: You can configure this integration to bi-directionally sync GitHub issue state, project columns, and labels with the status of an Aha! Roadmaps record. Your selections determine the status mapping options available in the next step.
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.
Issue state: Choose whether to enable GitHub issue state mappings. You configure the mapping in the next step.
Status labels: Choose whether to enable GitHub status mappings. When you enable them, you can map Aha! Roadmaps record statuses with GitHub status labels. You configure the mapping in the next step. Use the Status dropdown here to select the GitHub labels that you want to appear as options in the Mappings step.
Configure mappings
Next, configure how Aha! Roadmaps records map to your GitHub records. Aha! Roadmaps provides default mappings based on the most common customer use cases. You can remove the default mappings and add mappings that fit your team and workflow.
If you have configured required fields in GitHub, we recommend setting the Required flag on those fields in the custom layout associated with your workspace. This will ensure that you populate any required fields when you create records on the Aha! Roadmaps record creation form.
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 you map each field within the record between Aha! Roadmaps and GitHub Enterprise — as well as what relationship links exist for those records.
When you map an Aha! Roadmaps record type to GitHub issues, choose which issues the mapping covers:
Any issue: Every issue in the repository, regardless of type or hierarchy.
Top-level issue: Issues that do not sit under another issue.
Sub-issue: Issues that sit under a parent issue.
Issue (type: type name): Issues of a single GitHub issue type, such as Issue (type: Bug). These options appear when your GitHub organization defines issue types.
Earlier versions of the integration offered record types such as Issue (epic), Issue (feature), and Issue (requirement). If your integration already uses one of these legacy record types, it keeps syncing and the option appears with a (Deprecated) label. New integrations do not offer them, so use Top-level issue and Sub-issue to map hierarchies instead.
If you selected an Organization during the initial integration configuration, you can also map to GitHub custom fields.
-
If you want to map GitHub Pull Requests to Aha! records (one-way or bidirectionally), you can! Take a few steps to make sure you configure this correctly:
If you map Pull Requests, also map Head branch and Base branch. Map these fields even when the mapping direction is one-way, from GitHub to Aha! Roadmaps. In that case, create two custom fields and map the branch fields to them.
Base branch will usually be "master" or "main."
Head branch is the branch name of the code you would want to merge.
If you want to sync only certain GitHub issue types, map each Aha! Roadmaps record type to the Issue (type: type name) option for the issue type you want. The integration does not sync issues of any type you leave unmapped, so unrelated work stays out of your workspace.
If you want to map Aha! Roadmaps parent-child record hierarchies to GitHub parent issues and sub-issues, map the parent record type to Top-level issue and the child record type to Sub-issue. The default mappings already pair features with Top-level issue and requirements with Sub-issue.
If you want GitHub issue types to match your Aha! Roadmaps record types, map the Type field to the GitHub Issue type field, then click Configure to match values. New integrations include this field mapping on features by default.
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.
Enable the integration
With your records, field mappings, and statuses defined, click Save and continue to move to the Enable step, the last step in the workflow.
The Aha! GitHub App installs the integration's webhook automatically, so you do not need to set one up in GitHub. The Webhook section shows when the integration last received events from GitHub.
Then choose how Aha! Roadmaps sends updates to your development system. The default setting is Automatically send outgoing changes, which sends any change you make to an integrated record to GitHub automatically.
We recommend the Approve outgoing changes setting for teams that are unfamiliar with how the integration works. Teams new to the integration can use the approval step to review what Aha! Roadmaps sends to their development system and prevent unintentional changes.
If Aha! Roadmaps does not link a feature's parent release, or if you do not map releases to the development system, Aha! Roadmaps imports the feature into the first parking lot release. This is by design because parking lots hold unscheduled work.
Test the integration
Test your new integration by sending a feature to GitHub:
Navigate to Features -> Board.
Open a feature in Aha! Roadmaps, scroll to the Integrations field, and select Send to GitHub. After a few seconds, Aha! Roadmaps displays a link to the GitHub record on the feature. Open the link to verify that GitHub received the record correctly.
You can also bulk send a subset of features to GitHub.
Add additional security
2.0 integrations with on-premises tools have the option to include a client certificate for added integration security. This can also be called mutual TLS (mTLS).
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.
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.
Receive updates
You can receive updates when something changes in GitHub, including changes to the following:
Issues
Issue comments
Labels
Milestones
Project v2 items
Projects v2
Sub issues
Pull requests
The Aha! GitHub App delivers these updates through the webhook it installs, so you do not need to configure anything in GitHub. To confirm that updates are arriving, check the Webhook section on the integration's Enable step.
If you created your integration from the original GitHub tile, it keeps receiving updates through the repository and organization webhooks you already set up in GitHub.
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.