HaloCRM Guides
Azure DevOps Integration
In this guide we will cover:
- What is the Azure DevOps Integration?
- Connecting to DevOps
- Syncing between DevOps and Halo
- Halo Configuration Options
What is the Azure DevOps Integration?
The Azure DevOps integration allows you to sync tickets from Halo to work items in Azure DevOps and vice versa. This includes ticket/work item creation as well as updates to various fields.
Connecting to DevOps
Configure the Azure DevOps integration by navigating to Configuration > Integrations and enabling the module by hovering your cursor over the integration button and clicking the + icon.
Fig 1. Enable the module
Once enabled, click into the integration module to start configuration.
Upon clicking into the integration, click New in the top right corner to begin a new connection to Azure DevOps. This will prompt you to name your connection and provide an Azure DevOps instance URL.
Fig 2. Details for connection
From v2.250+ you will be able to choose the authentication method you wish to use for the integration. You can choose from:
- Using a personal access token
- Use Entra ID OAuth
On versions prior to this you will need to connect using a personal access token.
If setting up this integration for the first time, we advise connecting using Entra ID OAuth as personal access tokens are being deprecated by Microsoft in 2026.
Generate a Personal Access Token
This can easily be generated in Azure DevOps by clicking the “User Settings” icon next to your initials and selecting Personal access tokens from the drop down.
Fig 3. Personal access tokens area in Azure DevOps
Upon clicking this, you will navigate to a table of existing Personal Access Tokens where you can click “New” to configure a new one. Configure this token as you wish. Fields to note:
- Name is simply the name of the Personal Access Token in Azure DevOps. Provide something sensible.
- Expiration defaults to 30 days but you can set to your own desired time frame. We recommend taking note of this date so you can generate a new Personal Access Token when the time comes.
- Scopes has to do with the permissions required by Halo to perform this integration. The functionality simply involves creating and updating work items, so the only permission required is Work Items with Read, Write, & Manage.
Fig 4. Configure Personal access tokens in Azure DevOps
Please note that notes added to work items in Azure DevOps and subsequently synced to a Halo ticket will be attributed to the profile which generated the Personal Access Token. To ensure clarity, it is advisable to use a service account with a generic name to generate the Personal Access Token, minimizing confusion when notes are synchronized back to Halo.
Once the credentials for your connection are saved, you are able to test your connection to ensure everything has been configured correctly.
Fig 5. Test configuration
Generate OAuth Credentials (Recommended Method) (v2.250+)
To connect using OAuth credentials you will need to create an azure application in your azure tenant and generate the relevant credentials. We support the use of the following credentials:
- Client Secret
- Federated Credentials
- Certificate
Open the Entra Admin Centre (or similar) and navigate to the App Registration section. Click "New Registration".
Fig 6. New Registration
On the registration screen fill out:
Name: Give the application a sensible name to reference it with.
Supported Account Type: Choose Single Tenant. The Azure DevOps integration does not support a multi tenanted connection.
Redirect URI: Enter the "Redirect uri to register in Azure application for imports" found on your integration setup page in Halo. This will be visible after selecting "Entra ID OAuth" as the authentication method.
Fig 7. Application Details
Once registered, copy the "Application (client) ID" and "Directory (tenant) ID" from the Overview tab and store them safely, as these will be needed later.
Fig 8. Application and Directory ID
Now you will need to assign the required permissions to the application. The permissions the application needs can be found on the integration setup page in Halo.
To add permissions to the application head to the "API permissions" section, remove the default 'User.Read' permission, and add the following permission:
- user_impersonation
When adding this permission ensure this is added from the "Azure DevOps" API
Fig 9. Azure DevOps API
Once added your application permissions should look as shown in Figure 10.
Fig 10. Azure application with permissions
Now you will need to generate the credentials for this application. You will only need to follow one the of next sections of this guide in line with the credential type you are using.
Client Secret
In Azure, navigate to the "Certificates & secrets" tab, and open the "Client secrets" tab. Click "New client secret", fill out the description and choose an expiry. Microsoft limits this to a maximum of 2 years from creation. Once this generates, copy the "Value" (not Secret ID) and store it securely. It will no longer be visible once you leave this screen.
Fig 11. Copy the Secret Value
Now you have the client secret, Tenant ID and Application ID, head back to Halo and paste these values into the "Azure Application Details" on the integration setup page.
Federated Credentials
Once you have chosen Federated credentials as your credential type for the integration in Halo, you will need to choose the 'Agent Account to use for Federated Credential'.
Generate a Certificate
In order to use this credential type you will need access to a valid X.509 certificate. You will need this in both ".pfx" format (with access to the export password) and in ".cer, .pem or .crt" for Azure.
Once you have these, within Halo navigate to Configuration > Advanced Settings > Certificates. Create a new certificate entry by giving it a name, uploading the file, entering the password, and saving.
Fig 12. New Certificate Entry in Halo
In Azure, navigate to the "Certificates & secrets" tab, and open the "Certificates" tab. Click "Upload Certificate", upload the file, and give it a description before clicking "Add".
Fig 13. Upload Certificate in Azure
Now, back in Halo, head back to the integration setup page and input the Tenant ID, Application ID and choose the uploaded certificate before saving.
You should now have:
- Azure Application (client) ID
- Directory (tenant) ID
- Relevant credentials
Head back to Halo and plug these values into the integration setup page.
Fig 14. Azure Application Details plugged into Halo
Once saved there will be a "Sign in with Microsoft" button. Once pressed, you will be directed to the Microsoft Sign-In screen where you can sign in before being re-directed back to Halo. You will need to sign in with an account with appropriate permissions to access the resources you wish to import/update. The account will need permission to access all the work items you wish to import/update.
Syncing between DevOps and Halo
Syncing Projects from Azure DevOps to Products in Halo
Projects in Azure DevOps translate to Products in Halo. Knowing this, we must enable the Software Releases module in Halo to allow this integration to function. Find the module in Configuration and make certain that it is enabled.
Fig 15. Enable Software Releases Module
Now navigate back to the Azure DevOps integration page’s Projects tab. Here you can click the button Import Projects to sync over the projects in your connected Azure DevOps instance as products in Halo.
Tickets to Work Items
Action Configuration
To perform the creation of a work item in Azure DevOps, you must click a pre-configured action which is set with proper fields and system for syncing. To configure this action, navigate to Configuration > Tickets > Actions and click New in the top right corner to start configuring a new action.
Upon creating a new action, you will be prompted to enter various fields. Below we’ve noted the fields important for this integration.
Outcome Description - Text which shows after action has been performed.
Fig 16. Outcome description
Button Name - Text which shows on the button of the action.
Fig 17. Button name
Button Icon - Small picture which shows on the button of the action.
Fig 18. Button icon
System Use - The functionality which tells Halo to create a work item when this action is performed.
Fig 19. System Use
Work Item Type - Text box allowing you to denote a work item type to be created when this action is performed.
Fig 20. Work Item Type
Is a Quick Action checkbox (Not Required) - Will perform the action right at button press without prompting agents for fields to hit "Save".
Ticket type fields required to be filled out in order for a work item to be successfully created from a ticket in Halo:
- Product - This can be defaulted against the ticket type in Configuration > Tickets > Ticket Types > Click into desired ticket type.
Fig 21. Default product field
Required for Halo to know which project in Azure DevOps to create a work item under. You can also set the “Product” field against the bug-creating action and set it as mandatory to ensure this field is filled in prior to completing the action.
Syncing Action Notes to Azure DevOps
It is possible to sync additional action notes from Halo tickets to work items in Azure DevOps. To do this you must perform a preconfigured action with the Send to Azure DevOps checkbox. This must be checked at the time of the action to send the new note to the correlating work item in Azure DevOps.
Fig 22. Send to Azure DevOps field
Please note that it is not possible to push a comment to DevOps in the same action as creating a work item.
Tip: Create an action that has all fields you are syncing between Halo and Azure DevOps. This gives you one place to make any necessary changes in Halo.
Fig 23. Action field list
However, if you're doing this, please note that the Send to Azure DevOps field only controls when a comment is posted to the work item. If adding an action and altering other fields, even if the Send to Azure DevOps is unchecked, Halo will still push changes to other fields to the linked work item.
Syncing to Azure DevOps
Navigate to the integration page’s "Syncing to Azure DevOps" tab and find the "Fields to Sync" subtitle. Here you can indicate which fields Halo should sync to DevOps as tickets/updated are created and updated. As you add these to the multi-select, you are then prompted to adjust their configuration below.
Fig 24. Fields to sync to Azure DevOps
- Any mapped Fields
- Syncs custom fields.
- Choose product, which field in Halo, and which field in Azure DevOps.
- Area Path
- Work Item categorization field. Links to a category in Halo.
- Choose Area Path value and correlating Halo Category Value.
- Attachments
- Syncs attachments.
- No additional configuration is required.
- Iteration Path
- Work Item categorization field. Links to a category in Halo.
- Choose Iteration Path value and correlating Halo Category Value.
- Priority
- Choose which priority number in Azure DevOps correlates to which priority number in Halo.
- Status
- Choose which Halo status correlates to which Azure DevOps status.
- Start Date
- Syncs start date.
- No additional configuration is required.
- Target Date
- Syncs target date (sometimes called end date).
- No additional configuration is required.
Syncing from Azure DevOps
Now to configure this integration in the other direction! Namely, this would be to create a new ticket in Halo whenever a work item is created and to update Halo tickets which are linked to existing work items if those work items are updated.
You can either configure this using webhooks or our Halo integrator. Webhooks allow for an almost instant sync, whereas the Halo integrator will run the sync on a schedule. The Halo integrator comes with an added benefit of allowing additional filtering.
Webhooks
To do this, you must create two Web Hook Subscriptions in Azure DevOps (one for creation and one for updating). Steps:
Navigate to an Azure DevOps project and click "Project Settings" at the bottom-left corner of the screen.
Fig 25. Project Settings).
Click Service Hooks, then the + icon to create a new "Subscription", and select "Web Hooks" as the Service type. Click "Next".
Fig 26. Webhooks
Set the trigger to Work item created or Work item updated depending on which Web Hook Subscription you are creating. You may set more specific criteria for which work items trigger this new subscription or leave to all. Click Next.
Fig 27. Trigger
(1) Is the URL this Web Hook Subscription will push information to and can be found on Halo's Azure DevOps Integration Page's "Syncing from Azure DevOps" tab by clicking Work Item Updated or Work Item Created.
(2) Can be found in Halo’s Azure DevOps Integration Page’s "Syncing from Azure DevOps" tab.
(3) Can be found in this same integration page by clicking Edit and Generate to create a new password. Just remember to click Save after you are done.
Fig 28. URL and authentication
Set the rest of the page as follows and click Next.
Fig 29. Headers and what to send
Click Test and ensure that connection is successful. Click Save and you’re done!
Please note that the priority field value is not included in the work item created webhook unless manually changed on the new work item screen. To ensure consistent priority syncing, set the default priority of the ticket type in Halo to match the default priority value for work items in DevOps.
Halo Integrator
To use this syncing method, enable the checkbox 'Enable the Halo Integrator for the Azure DevOps integration' under the syncing from Azure DevOps tab. Then set the entities you would like to sync. You can choose how far back the sync checks for changes using the filed 'Check for work item updates for Tickets updated in the last X days'. For example, if I enter 5, when the sync runs any changes that have been made to work items in the last 5 days will update the related ticket in Halo, any changes older than 5 days will not update tickets.
To set which product in Halo a work item will be created under, use the work item filters. Found under the 'Syncing from Azure DevOps' tab, here you set filters in the table that will be applied to any work items syncing from Azure into Halo.
To set this up, add a filter to the table and choose which product the filter applies to. Then choose the field you would like to filter by and the operator. The operator determines if all the criteria in the table needs to be matched (AND), or only one criteria in the table needs to be matched (OR), for the filter to apply. Then set the filter type and the value. The available filter fields are:
- ID
- State
- Work Item Type
- Area Path
- Priority
- Changed Date
These filters will only apply to new work items being imported, updates to existing work items will still be imported only for work items linked to Halo tickets.
Note: The Halo integrator must be enabled for the module for these filters to apply.
Fig 30. Work items filter table
Halo Configuration Options
Ticket Type for New Tickets
- Allows you to set which ticket type is initiated in Halo when the Azure DevOps Web Hook Subscription fires.
User for New Tickets
- Allows you to set which user is assigned to new tickets coming from Azure DevOps.
- You can also set this to default to the person who created the work item with below check box.
Fig 31. Additional configuration settings
