Aha! Roadmaps | Integrate with GitLab

The GitLab integration allows you to push your features, activities and requirements in Aha! Roadmaps into Gitlab and get status changes back.

Because this is a two-way integration, your strategy can flow from Aha! Roadmaps to your development team in Gitlab, and receive status updates back as they complete the work.

You can also create multiple integrations per workspace to accommodate how the engineering team is split up, and give each GitLab integration a unique name to help keep them organized.

Click any of the following links to skip ahead:

• Prerequisites

• Features of the integration

  • From Aha! Roadmaps to GitLab

  • From GitLab to Aha! Roadmaps

• Create the integration

• Create an integration template

Prerequisites

Top

Features of the integration

From Aha! Roadmaps to GitLab

• One Aha! Roadmaps workspace can be associated with one or many GitLab projects. If the association is one-to-many, you need to set up different integrations for each workspace-project mapping. Be sure to rename your integrations by clicking on their name at the top of the integration page and specifying the project you are sending the features to.

• Features can be sent to GitLab either by sending the entire release, one feature at a time, or bulk sending a subset of features. Do this through the Integrations dropdown using Send to GitLab Issues.

• You can send an Aha! Roadmaps record's status to the GitLab issue as a label.

Only the most recently added label with the prefix Aha!: on the GitLab issue will sync to the status of the connected feature or requirement in Aha! Roadmaps. When updating the issue in GitLab from Aha! Roadmaps — any additional status labels will be removed and overwritten with the current Aha! Roadmaps status.

• When you send a feature to GitLab, an issue will be created for the feature.

• There are two ways to map requirements to issues. Each requirement can be mapped to a stand-alone issue, or the requirements can be converted to a checklist within the main issue (feature). If checklists are used, note that there are some significant caveats:

  • When checklist items are ticked, the status of the corresponding requirement in Aha! Roadmaps will not be updated.

  • Each time the feature is updated in GitLab using the Aha! Roadmaps Update GitLab menu item, the entire issue description will be overwritten, resetting the status of any checklist items that are already complete.

  • Tags from the feature will be inherited in the resulting GitLab checklist. At that point, no tag updates will come from Aha! Roadmaps for requirements. Only the description of a feature or requirement is sent. No tasks or comments are included.

• The name, description, tags, and attachments of a feature or requirement are sent but comments are not.

• Aha! Roadmaps releases will be created as milestones in GitLab. The milestone due date will be the end date of a user-defined release phase. This date will fall back to the release date if a release phase name is not defined or if the named release phase does not exist.

Master or Owner level permissions are required in GitLab to create milestones. If you try sending an Aha! Roadmaps release to GitLab and receive an error that looks like Remote error for 'create_feature': Error message: 403 Forbidden, the likely cause is that you don't have one of these permission levels. The solution is to have your permissions upgraded to one of these roles or to get a personal access token from someone who is. Here's a helpful chart of permissions in GitLab.

• After a feature is first sent to GitLab, changes to the name, description, and requirements can also be sent to GitLab by clicking Update GitLab in the Integrations dropdown on the features detail or drawer views or by sending all features in a release to GitLab again. New requirements will also be created in GitLab; however, issues that were created for an existing requirement are not deleted from GitLab if the requirement is deleted from Aha! Roadmaps. Likewise, if an attachment is deleted in Aha! Roadmaps, the corresponding attachment in GitLab is not deleted.

• With Add status labels enabled, the state of an Aha! Roadmaps feature corresponding to a GitLab issue can be changed to the desired Aha! Roadmaps state by adding a GitLab label with the Aha!: prefix and removing the label representing the feature's previous state. For example, to change the Aha! Roadmaps status from In development to Ready to ship, remove the label Aha!:In development and add the label Aha!:Ready to ship.

From GitLab to Aha! Roadmaps

• Status updates flow back from GitLab issues to Aha! Roadmaps if you've added the webhook.

• If you are sending labels, updates to the label on the GitLab issue will update the Aha! Roadmaps status.

Top

Create the integration

In Aha! Roadmaps

1. Enter your GitLab Personal Access Token. You can create a Personal Access Token via the GitLab API as well. Note: Some versions of GitLab prior to 8.8 may not support Personal Access Tokens and will require the use of a Private Token instead.

2. If you are using GitLab 9 or greater on your own server please enter your server URL ending with "/v4", with no trailing slash (e.g. https://example.com/api/v4). If you are using an earlier version of GitLab your URL should end with "/v3." If you are using gitlab.com leave the Server URL field empty.

3. Click the Test connection button.

4. After a short delay, you will be able to choose the project that the issues will be created in when sent from Aha! Roadmaps.

5. Set your desired feature and requirement mappings from Aha! Roadmaps to GitLab.

6. Define how you wish Aha! Roadmaps statuses to be mapped to the Open or Closed state of an issue in GitLab.

7. Choose whether or not you wish to send Aha! Roadmaps status to labels in GitLab.

8. Enable the integration.

9. Test the integration by going to one of your features in Aha! Roadmaps and selecting the Send to GitLab Issues option from the Integrations dropdown. You should then look at your project in GitLab and see that the feature (and any requirements) were properly copied to issues.

From GitLab

To receive updates when an issue is changed on GitLab, you have to set up a webhook for the GitLab project.

1. In Aha! Roadmaps, copy the webhook URL from the GitLab issues integration settings.

2. In GitLab, go to the settings page for the specific GitLab project and click on Webhooks in the Settings dropdown.

3. Paste the webhook URL into the URL field and leave the secret field blank. Uncheck the Push events box, and check the Issues events box for the trigger.

4. Click Add webhook.

Top

Create an integration template

Once you’ve configured your integration, you can save it as a template for others in your organization to use. To do so, click the More options button and select Use as a template, which will save the configuration as a new template. Once saved, it will be available to use for future integrations your team configures.

If you choose to use an existing template, its configuration will be applied to your new integration. Each configuration option will have a checkbox next to it allowing you to uncheck and apply a unique configuration on a per field basis.

Top