Aha! Develop | GitHub extension

Prioritize what to build next and manage your agile workflow in Aha! Develop. As work moves forward, link your user stories to their source code in GitHub — so you can get visibility into code progress and know when a feature has shipped.

Click any of the following links to skip ahead:

• Install the extension

• Configure the webhook

• Link pull requests to Aha! records

• View pull request details in Aha! Develop

• Automate statuses from pull requests (Develop Advanced)

• Auto-link to Aha! records in GitHub

• Use extension events for advanced customization

Install the extension

To install the GitHub extension in your Aha! account, open the extension library.

Note: You need to be an administrator with customizations permissions to install and apply extensions in your Aha! account, but users of any permission level can use them.

• Next to GitHub, click Install.

• Select your Aha! account.

• Your Aha! account customization settings will open. You need to be an administrator with customizations permissions to access this page.

• Click GitHub to install the GitHub extension.

• You will see a Success page. Click GitHub to configure it.

Top

Configure the webhook

Configure a webhook between GitHub and Aha! Develop to complete the integration.

Note: The extension will automatically link Aha! records to branches and pull requests in GitHub if you include the Aha! reference number (like APP-123) in the name of the branch or pull request.

From the GitHub extension configuration:

• Scroll down to the Contributions section and click Webhook from Github.

• Click the link icon beside the hidden URL to copy that URL.

In GitHub:

• Go to each repo that you want to integrate with Aha! Develop.

• Navigate to Settings Webhook, then Create a new webhook.

• Paste the hidden URL you copied from your Aha! account as the Payload URL.

  Note: The content type should be application/json.

• Select the following individual events:

  • Branch or Tag creation

  • Check runs

  • Pull requests

  • Pull request reviews

  • Pushes

  • Statuses

• Enable the webhook.

Note: Instead of doing this at the repo level, you can also create an organization-wide webhook that will work for all repos.

Top

Link pull requests to Aha! records

The extension will automatically link Aha! records to branches and pull requests in GitHub if you include the Aha! reference number (like APP-123) in the name of the branch or pull request.

If you need to manually link a pull request:

• Open the record.

• By the GitHub custom extension field you added, click the More options button.

• Click Link pull request. The Link pull request to record modal will open.

• Paste a link to your pull request.

• Click Enter.

Top

View pull request details in Aha! Develop

Next, add the extension's view contribution custom field to display pull request status and approvals in your Aha! Develop records.

To do this:

• Navigate to Settings ⚙️ Account Custom layouts.

• Select the record type you would like to customize, then click Add custom layout or hover over a layout that you wish to Edit. Either option will open the Custom layout builder.

• Click Extension fields on the left side of the page.

• Drag your GitHub extension field onto the record layout.

• Click Save layout to save your changes.

Repeat these steps for any other record type that needs to display GitHub information.

To view pull request details on a record, open any Aha! Develop record that you have linked to a GitHub PR.

• Click the top link to view the GitHub branch.

• Click the bottom link to view the GitHub PR.

• In Aha! Develop, you can see the PR status and reviews next to the PR link.

Top

Automate statuses from pull requests (Develop Advanced)

If you are a Develop Advanced customer, you can automatically sync the status of records in Aha! Develop with PR status changes. Open your team status automation settings by navigating to Settings ⚙️ Team. You will need to be an owner to do this.

The status automation settings are organized around every workflow extension you have enabled in your Aha! Develop account. Make sure you have also added an extension's view contribution fields to the relevant record types' custom layouts so you can see the related builds and PRs.

Click on an extension to get started.

• On the left of the Extension status automation modal, you will see every Extension event that can trigger a status change on an Aha! Develop record.

• On the right of the modal, you have your Team status workflow.

For any Extension event, choose the status you want your Aha! Develop record to move into. For example, a PR opened event could move the linked Aha! Develop record to Ready for code review status.

Top

Auto-link to Aha! records in GitHub

Use GitHub's autolinking feature to move back and forth seamlessly between your Aha! account and GitHub. GitHub PR description, comment, or title references to an Aha! record (e.g. CYCL-398) will then become links back to Aha! Develop.

You can create a new autolink reference to Aha! Develop with these guidelines:

• Reference prefix: The alphanumeric prefix on the epics, features, and requirements in Aha! Develop (e.g. CYCL-). You may need to add multiple autolink references in GitHub to support all of the projects in your Aha! account.

• Target URL: This URL is in the following format https://account.aha.io/records/<num>, where account is the subdomain for your Aha! account.

Top

Use extension events for advanced customization

The GitHub extension triggers events that other extensions can use for automation. The events will include the associated Aha! record as well as the full webhook payload from GitHub. See the table below for the full list of events.

In this example, we automatically add a to-do to the Aha! record when someone adds a documentation label to the related pull request.

aha.on({ event: 'aha-develop.github.pr.labeled' }, async ({ record, payload }) => {
  if (payload.label.name = 'documentation') {
    const task = new aha.models.Task();
    task.record = record;
    task.name = 'Write documentation';
    task.body = `Todo created from GitHub PR ${payload["pull_request"]["html_url"]}`;
    await task.save();
  }});

Top