Skip to main content

Azure DevOps Integration

Connect Azure DevOps Boards to sync work items between Clears AI and your Azure DevOps organisation.

note

Integration settings are only visible to users with the Admin role. Regular users cannot access or modify integration configuration.

What's Supported​

  • Azure Boards only. Clears syncs work items: their titles, descriptions, comments, tags, links and attachments. Azure Repos and Azure Pipelines are not used; connect your code with GitHub, GitLab or Bitbucket.
  • Azure DevOps Services only, the cloud service at https://dev.azure.com/<your-org>. Azure DevOps Server (on-premises, formerly TFS) is not supported.
  • One organisation per Clears account, and one Clears account per organisation.
  • One issue tracker per account. A Clears account uses Jira or Azure DevOps, never both. If Jira is connected, disconnect it before you connect Azure DevOps.
  • Clears owns status. Clears keeps its own status for every story, and workflows start only from Clears. Azure DevOps is updated only when a story moves to In Progress or Validation, once, on a best-effort basis (see Action Mapping). Changing a work item's state in Azure DevOps doesn't change the story's status in Clears and doesn't start a workflow.

Clears reads these work item types from your backlogs:

Azure DevOpsClears
EpicInitiative
FeatureEpic
User Story, Product Backlog Item, Requirement, Issue (Basic process)Story
BugStory, or Subtask when the team tracks bugs with tasks
TaskSubtask

Types that are hidden, or on no backlog level (for example the Agile process's Issue, or CMMI's Risk and Change Request), are not imported.

Connecting with the Clears App​

Connect Azure DevOps as the Clears app. Your Microsoft Entra admin approves the Clears app in your tenant, and your Azure DevOps admin adds it to the organisation, the same way you add a user. No one signs in on Clears' behalf, which gives you two things:

  • Changes show as Clears, not as a person. Work items Clears creates or edits, its comments and its tags show the Clears app as the author.
  • Access is not tied to anyone's account. A person leaving, changing role or resetting a password doesn't break the connection. You decide what the app can reach, and you can remove it at any time (Revoking access).

Before You Start​

Your organisation must be connected to Microsoft Entra ID. Check this in Azure DevOps under Organization settings → Microsoft Entra. An organisation that signs in only with personal Microsoft accounts can't use the Clears app, because it has no Entra tenant to approve the app in.

Two roles are needed. One person may hold both.

WhoNeeded for
An Entra admin who can grant tenant-wide admin consent (for example a Global Administrator or a Cloud Application Administrator)Step 1: approving the Clears app in your tenant
An Azure DevOps organisation admin (a member of Project Collection Administrators)Steps 3 and 4: adding the app to the organisation and allowing it to manage its service hooks

A Clears admin runs the steps from Settings → Integrations → Azure DevOps, and can hand step 1 to the Entra admin and steps 3 and 4 to the Azure DevOps admin.

Cost. The Clears app needs the Basic access level in your organisation. Azure DevOps counts it as a user, so it takes a paid Basic seat, unless one of the organisation's 5 free Basic seats is still unused. Stakeholder access isn't enough: a Stakeholder can't create new tags or delete work items, and Clears does both, so setup doesn't let you finish with Stakeholder access.

The Five Steps​

Go to Settings → Integrations → Azure DevOps and click Connect as the Clears app. The panel walks you through the steps below, in this order. In the panel, steps 3 and 4 are the checklist under Set up Clears in Azure DevOps, and step 5 ends with Finish connecting.

  1. Click Approve Clears in Microsoft Entra. Clears sends you to Microsoft's admin consent page, where the Entra admin must sign in. If you aren't the Entra admin, click Get a link for an Entra admin and send them the link. It works for 10 minutes, and they open it in a browser where they are signed in to Clears as an admin of your Clears account.
  2. Microsoft's page names the Clears app and asks you to accept, for your whole organisation, the permissions it requests on Azure DevOps. Accepting adds the Clears app to your tenant as an enterprise application (a service principal). Consent alone gives the app access to no organisation and no project. Azure DevOps lets it in only after step 3.
  3. The tenant sign-in. Right after you accept, Microsoft asks you to sign in to the same tenant once more. This tells Clears which tenant approved the app. Sign in with an account that is a member of that tenant, not a guest invited from another tenant. This sign-in also lets Clears list the Azure DevOps organisations you belong to, once, for step 2. Clears doesn't keep that access, and it reads no mail.
  4. Back in Clears. Microsoft sends you back to the Azure DevOps settings page, and Clears confirms the approval as the page loads. Finish this in the same browser within 5 minutes, signed in to Clears as an admin of your Clears account. The panel shows Clears was approved in your Microsoft Entra tenant.

Step 2: Choose the Organisation​

The Organisation dropdown lists the Azure DevOps organisations that the person who signed in at step 1 belongs to, in the tenant that approved Clears. Choose yours and click Continue. If there is only one, it is already selected.

If your organisation isn't listed, choose Type another name and enter the organisation's name: the part after dev.azure.com/, for example contoso for https://dev.azure.com/contoso. This happens when the person who signed in isn't a member of the organisation, or when Clears couldn't read the whole list.

Clears checks that the organisation exists, that it belongs to the tenant that approved Clears, and that it isn't already connected to another Clears account. Clears tracks the organisation by its id, not its name, so renaming it later doesn't change which Clears account it belongs to. To pick another organisation later in the setup, click Change.

Step 3: Add Clears to the Organisation​

The Azure DevOps organisation admin does this in Azure DevOps:

  1. Go to https://dev.azure.com/<your-org> → Organization settings → Users → Add users
  2. Search for the Clears app by its name. It's the enterprise application created in step 1, and the panel shows its name
  3. Set Access level to Basic. Don't use Stakeholder (cost)
  4. Under Add to projects, choose every project Clears should work in, with the default Contributors group
  5. Click Add

Clears can only see and change work items in the projects you add it to here.

Step 4: Allow Clears to Manage Its Service Hooks​

Azure DevOps tells Clears about work item changes through service hooks. The app needs the organisation's service hooks permission to create its own. An organisation admin grants it once, with one Azure CLI command:

  1. Install the Azure CLI, or use the Bash shell of Azure Cloud Shell, which has it already

  2. Add the Azure DevOps extension:

    az extension add --name azure-devops
  3. Sign in as the Azure DevOps organisation admin:

    az login

    If your tenant has no Azure subscriptions, use az login --allow-no-subscriptions.

  4. Once step 3 is done, the panel shows the exact command for your organisation under Allow Clears to manage service hooks. Click Copy and run it. It has this form:

    az devops security permission update --org https://dev.azure.com/<your-org> --namespace-id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --token PublisherSecurity --allow-bit 7 --subject '<descriptor>'

    Copy it from Clears rather than typing it: <descriptor> is the Clears app's own identity in your organisation, which only the panel shows. The command is quoted for Bash or zsh (Azure Cloud Shell's Bash works); in PowerShell or cmd the quoting can break.

The command allows View, Edit and Delete on service hook subscriptions, and changes nothing else. It grants no access to repositories, pipelines, board settings or other organisation settings.

Step 5: Check Again, Then Finish​

  1. Click Check again. Clears checks, as the app and live each time you click, that:

    • Add Clears to the organisation - the app was added to the organisation (step 3) with Basic access or higher
    • Allow Clears to manage service hooks - the app has View, Edit and Delete on service hook subscriptions (step 4)
    • Projects - which projects the app can see

    Each item shows ✅ Done, ❌ Not done or Couldn't verify, with what to do next. Until the app is added, the other items can't be checked yet.

  2. Optionally choose the projects Clears should work in, up to 50. Leave the choice empty and Clears works in every project it was added to (see Projects).

  3. Click Finish connecting. It turns on once Clears is added with Basic access and allowed to manage service hooks. If Clears couldn't read the app's access level, that item shows Couldn't verify and doesn't block you, but make sure in Organization settings → Users that the app has Basic.

Clears runs the checks once more, stores the connection, creates its service hooks and starts importing your work items. The card then shows Connected to <your-org> as the Clears app, and which name your changes show under in Azure DevOps.

What Clears Can Access​

  • In your Entra tenant: the Clears enterprise application, created by your admin consent. Clears uses it only to get Azure DevOps access for your tenant.
  • In your Azure DevOps organisation: what you give it in step 3, a Basic access level and membership in the projects you added it to. With these, Clears reads, creates, updates and deletes work items, including their comments, tags, links and attachments, in those projects only. A project limit set in Clears narrows this further; it never widens it.
  • The service hooks permission from step 4, which covers service hook subscriptions only.

Clears is not an organisation admin, and it can't reach projects you didn't add it to.

Switching from a User Connection​

Next to the Clears app, the card offers Sign in with your account: Clears then acts as you, every change shows under your name, and the connection stops working if your sign-in expires or you lose access. The Clears app is recommended.

If your account is already connected as a user, click Switch to the Clears app and follow the same steps. The user connection keeps working until you click Finish connecting. From then on:

  • Clears acts as the app. Changes made before the switch keep their original author in Azure DevOps.
  • Clears recreates its service hooks as the app, one set per project, and then removes the ones the user connection created, using the previous user's sign-in once. If that sign-in no longer works (for example the person left), the old hooks stay and Azure DevOps sends some updates twice. The Service hooks section then says so: click Remove the previous user's service hooks and sign in to Microsoft as the person who originally connected, or as another account that may manage the organisation's service hooks, or contact Clears support. You can't remove these hooks from Azure DevOps' own pages.

Projects​

Once connected, the Projects section shows where Clears works:

  • Clears works in all projects of <your-org> - every project the app was added to in Azure DevOps. Click Limit to specific projects to choose some of them.
  • Clears works only in these projects of <your-org> - the list you chose. Click Edit to change it, or Remove limit to work in every project again.

The limit only narrows what the app can reach. To give Clears a new project, add the app to it in Azure DevOps (Organization settings → Users, or the project's own settings), then include it in the limit if you use one.

When you change the limit, the service hooks follow at once: new projects get theirs and projects that left the limit lose them. A project you add the app to later gets its service hooks within the hour, or at once with Re-register hooks.

Status and Action Mapping​

These sections appear on Settings → Integrations → Azure DevOps once an organisation is connected.

Status Mapping​

Open Workflows and Statuses to see, for each project (with its process) and work item type, every Azure DevOps state, its State Category and the Clears Status it maps to.

Clears fills these mappings in for you the first time it meets a project, from each state's category in Azure DevOps, not its name:

State categoryClears status
ProposedTo Do
In ProgressIn Progress
ResolvedIn Progress
CompletedDone
RemovedDone (counted as cancelled, never as completed work)

If one state name has different categories on different work item types in a customised process, it maps to In Progress.

To change a mapping, use the Status mappings table under the projects. Mappings are account-wide: one per state name, for every project and work item type. Clears only adds mappings for states it hasn't seen; it never changes one that exists, so your edits are kept.

Issue Type Mappings works the same way for work item types: Clears adds each backlog type with the level from What's Supported, and you can change it. A type's level is account-wide, so the first project Clears meets, or your edit, decides it for every project.

Action Mapping​

Open Actions Mapping to choose the status each Clears action applies:

ActionWhat it sets
ApproveThe status applied when a story is approved
CancelThe status applied when a ticket is cancelled
In Progress (Azure DevOps mirror)The state a work item moves to when Clears moves its story to In Progress
Validation (Azure DevOps mirror)The state a work item moves to when Clears moves its story to Validation

Because Clears owns status, these two mirror moves are the only status changes Clears makes in Azure DevOps. Each is one best-effort attempt. When you haven't chosen a state, Clears looks for a state named exactly In Progress or Validation in the work item's type; for In Progress, it otherwise uses the type's first state in the In Progress category. If no state fits, the work item stays where it is, and the story shows a note so you can set the mapping. Done is never mirrored to Azure DevOps.

Custom Fields​

Open Field Mappings to see which Azure DevOps field each Clears field reads. Azure DevOps fields are named by their reference name in brackets, for example [System.Title] or [Microsoft.VSTS.Scheduling.StoryPoints]. Clears maps these by default:

Clears fieldAzure DevOps field
SummaryTitle
StatusState
AssigneeAssigned To
PriorityPriority
TeamArea Path
SprintIteration
Due date (initiatives and epics)Target Date
Story pointsThe work item type's own field: Story Points (Agile), Effort (Scrum) or Size (CMMI)
DescriptionThe work item's description (Repro Steps on a bug that has it)

To change one, edit its Azure DevOps Field with another reference name in brackets. The sprint must be one iteration field, [System.IterationId], with nothing after it.

To bring in a field of your own, click + Add custom field, enter a Field ID and a Display Name, choose its type, then map it to the Azure DevOps field. Fields your inherited process adds have reference names that start with Custom., for example [Custom.RiskLevel].

A custom field of type Long text can also be edited in Clears, and the change is written to the mapped Azure DevOps field. A field mapped to a calculated value, or to no Azure DevOps field, can't be written back.

Service Hooks​

Azure DevOps tells Clears about work item changes through service hooks. Clears creates and keeps its own, per project: one for each event (work item created, updated, deleted, restored and commented) in every project Clears works in. There is no webhook for you to set up.

The first set is created in the background after Finish connecting, one Azure DevOps call per project and event, so the list fills in over the next few minutes, longer for many projects.

Azure DevOps stops sending updates to a service hook after a failed delivery, and only Clears turns it back on. Clears checks its hooks when you connect, when you click Re-register hooks, and once an hour, and fixes what is missing or turned off.

Open Service hooks to see each event with its status in Azure DevOps (Not registered when it's missing), and the health line:

Hooks last checked: 5m ago — Healthy

HealthWhat it means
HealthyThe last check was less than 3 hours ago, it succeeded, and every hook was in place
FailingThe last check failed, or Azure DevOps refused to create or turn on at least one hook. Updates from the affected projects may not reach Clears
Not checked recentlyNo check in the last 3 hours, so a hook Azure DevOps turned off may still be off
Not known yetNo check has been recorded yet, for example right after you connect

When the health is Failing or Not checked recently, the line says why, and admins also see a banner on the board that links to this section. Click Re-register hooks to run the check now. It runs in the background and can take a few minutes for many projects; the line updates when it's done. If it keeps failing, see Service hook health.

Webhook Logs lists recent deliveries, from Azure DevOps' own delivery history.

Troubleshooting​

The Setup Checks​

What the panel showsWhat it meansFix
Add Clears to the organisation: ❌ Not done, the app isn't addedThe Clears app isn't a user of the organisation yet. Until it is, the other items can't be checked and no command is shown.Do step 3, then click Check again. Make sure you added the Clears enterprise application, in the organisation you chose in step 2.
Add Clears to the organisation: ❌ Not done, Clears "needs Basic"The app has Stakeholder access (or none). It can't create new tags or delete work items. Finish connecting stays off.In Organization settings → Users, change the app's access level to Basic, then Check again.
Add Clears to the organisation: Couldn't verify the access levelClears couldn't read the app's access level. This doesn't block finishing.Confirm in Organization settings → Users that the app has Basic.
Allow Clears to manage service hooks: ❌ Not doneThe app doesn't have all three of View, Edit and Delete on service hook subscriptions.Run the command from step 4 as an organisation admin, then Check again.
Projects: ❌ Not doneClears can't read any project of the organisation.Add the app to the projects Clears should work in (step 3), then Check again.
Any item: Couldn't verify, "Azure DevOps didn't answer this check"Azure DevOps couldn't be reached, failed, or gave an answer Clears couldn't read.Wait a moment and click Check again. If it keeps failing, contact Clears support with the item and the reason shown.

If Finish connecting says Clears must be added with Basic access and allowed to manage its service hooks, something changed since the last check, for example the access level. Click Check again and fix what fails.

Refusals​

MessageWhereWhat to do
Clears wasn't approved: the admin declined, or the Microsoft sign-in didn't complete.Step 1Start step 1 again, as an Entra admin who can grant admin consent, and accept.
The approval expired or was replaced by a newer one. Start the approval again.Steps 1 and 2The approval link expired or was already used, a newer one replaced it, or it wasn't confirmed in Clears within 5 minutes. Start step 1 again from Clears and finish it in one go, in the same browser.
The Microsoft Entra tenants don't match.Step 1The tenant sign-in used a guest account, or an account of another tenant. Start step 1 again and sign in with an account that is a member of your tenant.
The Microsoft Entra tenants don't match.Step 2The organisation belongs to another Entra tenant than the one that approved Clears. Check the tenant under Organization settings → Microsoft Entra, then run step 1 in that tenant, or choose an organisation of the approved tenant.
That Azure DevOps organisation wasn't found.Step 2Enter just the part after dev.azure.com/, not the full URL or a project name. Check that the organisation is connected to Microsoft Entra ID (Before you start).
That Azure DevOps organisation is already connected to another Clears account.Steps 2 and 5An organisation can be connected to one Clears account only. Disconnect Azure DevOps in the other Clears account first, or contact Clears support if you don't know which account holds it.

Two more messages you may see:

  • Microsoft Entra ID refused the Azure DevOps sign-in; an admin must reconnect - Microsoft won't give Clears access for your tenant, for example because the Clears enterprise application was deleted or its consent revoked. Do step 1 again.
  • Jira is connected to this account - disconnect Jira in Clears first.

Service Hook Health​

HealthWhat to do
HealthyNothing.
FailingClick Re-register hooks. If it keeps failing, check the app's service hooks permission, then contact Clears support. If the section says the previous user's service hooks are still active, see Switching from a user connection.
Not checked recentlyClick Re-register hooks. If it doesn't return to Healthy within a few hours, contact Clears support.
Not known yetWait for the first check, or click Re-register hooks. If it stays this way, contact Clears support.

Duplicate Service Hooks After the Clears Address Changed​

Clears recognises its service hooks by the Clears address they send updates to. If that address changes, for example a new hostname for a Clears appliance, Clears creates a new set and leaves the old ones in Azure DevOps. Delete the old ones yourself: in each project open Project settings → Service hooks and remove the subscriptions whose URL is the old Clears address.

Revoking Access​

Do all three to remove Clears completely:

  1. Disconnect in Clears - see Disconnecting
  2. Remove the app from the organisation - in Azure DevOps, Organization settings → Users, select the Clears app and remove it. This frees its Basic seat and ends its access to every project at once
  3. Delete the enterprise application in Entra - in the Microsoft Entra admin center, Enterprise applications, open the Clears app, then Properties → Delete. This removes the consent from step 1

Disconnect in Clears first, while the app still has access, so it can delete its service hooks. If you remove the app first, its service hooks stay in Azure DevOps and you delete them yourself under Project settings → Service hooks. They can't deliver to Clears anymore either way.

Disconnecting​

Click Disconnect on the Azure DevOps card and confirm. Clears deletes its service hooks in your organisation, forgets the connection and releases the organisation, so another Clears account could connect it later. Syncing and status updates stop until you connect again.

Disconnecting doesn't remove the Clears app from your organisation or your Entra tenant; see Revoking access.