This two-way integration allows you to push your features and requirements in 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 tools 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 to 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 sub-set of features. This is done through the Actions menu 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 Aha!'s Update GitLab menu item, the entire issue description will be overwritten, reseting 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 using the Update GitLab item in the Actions menu 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 in order 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! provided 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 your own GitLab server please enter your server URL without a trailing slash (https://example.com/api/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 the issues will be created in was 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 using the Send to GitLab Issues item in the Actions menu on the features page. 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 use of a Private token instead.
To receive updates when an issue is changed on GitLab you have to setup a webhook for the GitLab project.
- In Aha!, copy the Webhook URL from the GitLab issues integration settings.
- On 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 actions menu and select “Use as a template”, which will save the configuration as a new template. Once saved, it will be available for 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 check box next to it allowing you to uncheck and apply a unique configuration on a per field basis.