Coming soon: We are introducing a fresh new look for record drawer and details pages on September 30, 2020. This article describes the current experience. Preview the upcoming improvements in your account now so you can get familiar with the new way of working in Aha!
The GitLab integration allows you to push your features, activities and requirements in Aha! into Gitlab and get status changes back.
Because this is a two-way integration, your strategy can flow from Aha! to your development team in Gitlab, and receive status updates back as they complete the work.
Click any of the following links to skip ahead:
- Features of the integration
- Create the integration
- Create an integration template
|Required user permissions:
|Required user permissions:
|Associated record types||
Features of the integration
From Aha! to GitLab
- One Aha! 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 Send dropdown using Send to GitLab Issues.
- You can send an Aha! record's status to the GitLab issue as a label.
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.
- 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! 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.
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.
- 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 detail drawer 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."
From GitLab to Aha!
- Status updates flow back from GitLab issues to Aha! if you've added the webhook.
- If you are sending labels, updates to the label on the GitLab issue will update the Aha! status.
Create the integration
- 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.
- 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.
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.
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.