Azure DevOps Integration: Setup and Sharing

Overview

The Azure DevOps integration creates work items from Spotto recommendations and links them back to the recommendation. Configure it for a company, choose the destination project and work item type, then share recommendations to Azure DevOps.

This guide covers Azure DevOps Services at https://dev.azure.com. Spotto uses a Microsoft Entra service principal with a client secret. Personal access tokens are not supported.

Prerequisites

• An Azure DevOps organization connected to Microsoft Entra ID.
• Permission to register an application in that tenant, or access to an existing application and its credentials.
• An Azure DevOps administrator who can add the application identity and grant project permissions.
• Permission to edit the company's integrations in Spotto.

Open your Azure DevOps organizations to find your organization. Its address is https://dev.azure.com/your-organization. Use the organization segment from that URL in Spotto; it can differ from your company or tenant display name.

Create the service principal

1. In the Microsoft Entra admin center, open App registrations → New registration in the tenant connected to Azure DevOps.
2. Enter a descriptive name, choose accounts in this organizational directory only, and leave the redirect URI empty.
3. Register the application and record its Application (client) ID and Directory (tenant) ID.
4. Open Certificates & secrets → Client secrets → New client secret. Record the secret Value, which is shown only once. The secret ID is not the credential.
5. Record the expiry date and replace the secret in Spotto before it expires.

You can use an existing app registration, including the app used for a cloud account, but enter its credentials explicitly in the Azure DevOps integration. Connecting an Azure cloud account does not configure this integration or grant Azure DevOps access.

Spotto currently accepts client secrets for this integration. Microsoft's broader guidance also covers other credential methods; those are not setup options in this form. See Microsoft's service principal setup guide.

Grant Azure DevOps access

1. Open your organization in Azure DevOps, then Organization settings → Users → Add users.
2. Find the service principal by its application display name. Add it explicitly, select the destination project, and assign an access level that supports the required work tracking features. A paid access level consumes a license for the application identity.
3. Grant View project-level information for the destination project.
4. In Project settings → Project configuration → Areas, open the target area's Security settings. Grant View work items in this node and Edit work items in this node. Check inherited permissions and any explicit denies.
5. If Spotto will create new tags, grant Create tag definition and an access level that permits that operation, such as Basic. Existing tags do not require creation permission.

Use a dedicated project group for the integration so its permissions can be reviewed together. The project's Contributors group is a broader alternative if that matches your organization's policy.

Azure DevOps access levels, group membership, and project permissions control access. Azure subscription RBAC and Entra application API permissions do not grant these permissions. If an administrator needs an object ID to add the identity programmatically, use the service principal object ID under Enterprise applications, rather than the application object ID under App registrations.

See Microsoft's application identity access guidance and work tracking permission settings.

Configure the company in Spotto

1. Open Companies, edit the company, and select Integrations.
2. Enable ticketing integrations and select Azure DevOps.
3. Enter the organization name, tenant ID, client ID, and client secret value. An organization URL is optional. When editing saved credentials, leave the secret blank to retain it.
4. Choose the Project and a Work item type supported by that project. Available types depend on the project's process, so use the list rather than assuming every project has the same types.
5. Choose a Team work area if the work should appear on a particular team's boards. Set an iteration when targeting a sprint. Assignee, tags, and priority are optional defaults.
6. Select Test Azure DevOps connection beside the save controls. Resolve any errors, then save the company.

The test uses the current form values, including a newly entered secret or the saved secret. Testing does not save your changes. With a project and work item type selected, the test asks Azure DevOps to validate a work item without saving one. Without a selected work item type, a successful test confirms access to project metadata rather than full work item creation rules.

Choose the team's work area

Team work area is Spotto's name for the Azure DevOps Area Path. A work item belongs to a project; the team's area settings determine which boards include it. Setting an assignee does not select a board.

For example, choose Platform\Operations when the Operations team's board includes that area. Ask your Azure DevOps administrator to check Project settings → Teams → your team → Areas if you are unsure. Several teams can include the same area, so a work item can appear on more than one board.

Iteration settings, work item types, and board filters also affect visibility. A blank team work area does not select a team or its defaults. See Microsoft's area and iteration guidance.

Use parent credentials

A child company can select Use parent credentials to use its immediate parent's saved Azure DevOps credentials. The parent must have a working integration. The child can keep its own project and routing defaults. Parent credential inheritance does not automatically extend through multiple parent levels.

Share and validate a recommendation

1. Save the integration, open a recommendation, and select its share action.
2. Choose Azure DevOps. Review the destination and any routing overrides offered in the share dialog.
3. Share once. Creation runs in the background; submitting the share does not mean the work item already exists.
4. When processing finishes, follow the work item link from Spotto and check its project, work item type, team work area, and iteration.

A separate cloud resource sync is not what creates the work item. Share creation requires Spotto's background request processing. If a request is delayed, check its processing status with support before sharing again, to avoid duplicate work items.

Troubleshoot setup and sharing

Symptom	What to check
Azure DevOps is shown as unconfigured in the share dialog	Save an enabled Azure DevOps integration for the company you are sharing from. Confirm whether the share uses that company or its parent. Refresh the view after saving.
Test button is disabled	Enter the organization, tenant ID, client ID, and a secret, or retain the saved secret. The integration must be enabled.
Connection test fails	Confirm the secret value and expiry, connected tenant, explicit organization membership, project access, and area permissions.
TF401444: Sign-in required	Add the service principal explicitly to the Azure DevOps organization and grant its required access level and permissions.
Project list is empty	Confirm the organization URL segment and grant the application identity access to at least one project.
Connection succeeds but creation fails	Select the intended project and work item type before testing. Check required fields and rules in the project's process. A metadata-only test cannot validate creation rules.
Work item exists but is missing from the team's board	Open the item directly and compare its Area Path, iteration, and type with the team's settings and board filters.
Share remains pending	Background processing may be delayed or unavailable. Ask support to inspect the request before submitting another share.

When contacting support, include the company, approximate share time, project, and error message. Do not send client secrets in screenshots or support messages.