Azure Devops sync

Connect Azure Devops to aqua to create and sync issues

If you run your projects in aqua and Azure DevOps simultaneously, you can set up synchronization of tickets between both systems so everyone stays informed about the changes.

The Azure DevOps sync includes:

• Title

• Status

• Assigned to

• Description

• Images in description

• Files

To set up the integration, we recommend following the instructions and making some preparations in advance.

Mapping of the users

When you use the field 'Assigned to' in aqua or Azure Devops, for the proper sync of the items, you need to map the users between aqua and Azure Devops. If the users are not properly mapped and you select 'Assigned to' in aqua or Azure Devops, the sync will fail and items won't be synced.

Azure Devops Cloud

• To enable synchronization, matching email addresses are required in both systems when using the 'Assigned to' field.

• If the 'Assigned to' field is not used, user matching is not necessary.

Azure Devops Server

• For synchronization, the username in aqua must match the username and display name in Azure.

• Please note that the display name and username in Azure should be the same for proper synchronization.

• This applies only if you intend to use the 'Assigned to' field.

aqua side preparation

First, create an aqua technical user:

• Go to the user administration section in aqua.
• Add a new technical user.

• Assign a technical license to this user.

This user will handle all sync operations in aqua and keep the history of the ticket updated.

Creating a technical user in aqua

Then, select the aqua project you plan to sync with Azure DevOps project and add the technical user to it with the 'Project Manager' role, ensuring they have all the necessary permissions to work with the items.

Project assignment

Next, go to the template page.

For the items you plan to sync (requirements or defects), define the status values. Make sure these values match exactly in both aqua and Azure DevOps for successful syncing.

For example: If the Azure DevOps status field has the following values:

• To do

• Doing

• Done

Azure devops status values

Then, in aqua, it should also be:

• To do

• Doing

• Done

aqua status values

Azure Devops side preparation

To set up the integration, you need an Azure DevOps token. Click the settings icon and select 'Personal access tokens' to create it.

Then click the ‘New Token’ button.

Create an Azure Devops token

Once the sidebar appears, give the token a unique name. We recommend selecting the following options:

• Organization access: All accessible organizations

• Expiration: Any timeframe

• Scope: Full scope

Token settings

As a security measure, you can grant access to only one organization. However, if you do this, you'll need to manually provide the organization name when setting up the sync integration.

Once you save the token, copy it and store it safely for further setup.

Setting up an integration

Navigate to the integrations page and switch to the 'Project' tab.

Note that Azure DevOps sync integration is supported only at the project level.

Then, click the 'Configure' button.

Integrations page

Once the modal opens, select the aqua project you want to sync. Then, choose the previously created tech user.

Then select whether you want to set up integration with Cloud or Server version of Azure Devops (available in the upcoming version 24.135)

Setting up integration for Cloud Version

First, rovide a generated a global token with access to all organizations, the system will automatically pull and show all available Azure DevOps organizations for sync. If you created an organization-specific token, please enter the organization name exactly as it appears in Azure DevOps.

After providing the token, all available projects within the selected organization will be pre-populated. Select the Azure DevOps project you want to sync with.

Next, define which aqua items you want to sync. Currently, you can sync only requirements and defects with Azure DevOps epics, issues, and tasks.

When the project is selected, the available item types from Azure DevOps will be pre-populated in the dropdown. Choose the item type you want to sync from the list.

Azure Devops sync set up modal

Then, define the direction of the sync:

• Bidirectional: From the integration setup, all existing and newly created tickets in both systems will sync in both directions. For example, if you edit a ticket in aqua, the changes are reflected in Azure DevOps, and if you modify the same ticket in Azure DevOps, the changes are transferred back to aqua.

• To aqua: From the integration setup, all existing and newly created tickets in Azure DevOps will sync only to aqua. For example, if you edit a ticket in Azure DevOps, the changes are reflected in aqua, but if you modify the same ticket in aqua, the changes are not transferred back to Azure DevOps.

• To Azure DevOps: From the integration setup, all existing and newly created tickets in aqua will sync only to Azure DevOps. For example, if you edit a ticket in aqua, the changes are reflected in Azure DevOps, but if you modify the same ticket in Azure DevOps, the changes are not transferred back to aqua.

Azure Devops sync set up modal

The sync direction for each item type can be set up individually. For example, you can sync defects in both directions and requirements in only one preferred direction.

After the integration is set, all existing tickets will start synchronizing based on the defined preferences.

The sync runs automatically every 10 seconds.

If you want to disable sync, you can do so either for the whole sync or for a specific item type.

Disabling the sync for an item

Fully disabling the sync

You can also change the sync direction by selecting a different option from the dropdown.

Sync direction fields

Setting up the integration for Server Version

First, select aqua project and aqua technical users.

The select the 'Server' version.

When you select the 'Server' option, a new field appears where you need to provide Azure Devops base URL, you can copy it from the browser.

Then provide a generated API key.

For the Server version, disregarding the type of the token, aqua will automatically load all the available projects.

Once the projects from Azure side loaded, you can proceed with setting up a sync same way as decribed above for Cloud version.

Please note that you can't change the aqua project, Azure DevOps project, or issue type once the sync is set up. If you need to make these adjustments, we recommend removing the sync completely and setting up a new one.