This two-way integration allows you to push your features and requirements from Aha! to GitLab as issues and get status updates back.
When you have prioritized your features and defined your product roadmap in Aha!, you can send features to GitLab for your engineering team to work on. You can send features individually or in bulk for an entire release. This makes setting product strategy and sharing visual roadmaps easy for the product management team, while engineering can continue to work in GitLab.
All development tool integrations are configured under Settings > Product. You need to be a Product Owner in Aha! to set up this integration for a product.
- One Aha! product can be associated with one or many GitLab projects. If the association is one too many, you need to set up different integrations for each product-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. This is done through the Send dropdown using Send to GitLab Issues.
- The status in Aha! can be sent to the GitLab issue as a label.*
- When a feature is sent 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! will not be updated.
- Each time the feature is updated in GitLab using the Aha! 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! 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! 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.
- 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 Send dropdown on the features page 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! Likewise, if an attachment is deleted in Aha!, the corresponding attachment in GitLab is not deleted.
- With Add status labels enabled, the state of an Aha! feature corresponding to a GitLab issue can be changed to the desired Aha! 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! status from In development to Ready to ship, remove the label "Aha!:In development" and add the label "Aha!:Ready to ship".
* Note: 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! When updating the issue in GitLab from Aha! — any additional status labels will be removed and overwritten with the current Aha! status.
** Note: Master or Owner level permissions are required in GitLab to create milestones. If you try sending an Aha! release to GitLab and receive a "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.
What comes back
- Status updates flow back from GitLab issues to Aha! if you've added the webhook
- If sending labels, updates to the label on the GitLab issue will update the Aha! status
You need to be a Product Owner in Aha! to set up this integration.
Please carefully follow these instructions to ensure that the integration is properly configured.
Create the integration in Aha!
- Enter your GitLab Personal Access Token.*** You can create a Personal Access Token via the GitLab API as well.
- 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.
- Click the Test connection button.
- After a short delay, you will be able to choose the project that the issues will be created in when sent from Aha!
- Set your desired feature and requirement mappings from Aha! to GitLab.
- Define how you wish Aha! statuses to be mapped to the Open or Closed state of an issue in GitLab.
- Choose whether or not you wish to send Aha! status to labels in GitLab.
- Enable the integration.
- Test the integration by going to one of your features in Aha! and selecting the Send to GitLab Issues option from the Send dropdown in the integrations section. You should then look at your project in GitLab and see that the feature (and any requirements) were properly copied to issues.
*** 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.
To receive updates when an issue is changed on GitLab, you have to set up a webhook for the GitLab project.
- In Aha!, copy the webhook URL from the GitLab issues integration settings.
- In GitLab, go to the settings page for the specific GitLab project and click on Webhooks in the Settings dropdown.
- 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.
- Click Add webhook.
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.