Skip to main content

Onboarding: Azure DevOps Boards

This guide walks through the full onboarding wizard for teams that track their work in Azure DevOps Boards. In this mode, Clears AI syncs work items between Azure DevOps and the Clears AI Board, letting you trigger AI execution on stories from your existing Azure DevOps backlog.

On the wizard's first screen, Choose your mode, select Azure DevOps Boards and click Continue.

note

Clears supports Azure DevOps Services (dev.azure.com) and Azure Boards only, and Clears owns status: it keeps its own status for every story and only mirrors In Progress and Validation back to Azure DevOps. See What's Supported for the details.

Step 1: Choose Your VCS Provider (Required)​

The first step asks you to select a version control provider. Clears AI supports three providers:

ProviderConnection MethodDescription
GitHubGitHub AppConnect to GitHub for repositories and pull requests
BitbucketOAuthConnect via OAuth for Bitbucket Cloud workspaces
GitLabOAuthConnect via OAuth for GitLab.com groups and projects

Select your provider and click Continue. You can add more providers later from Settings → Integrations.

note

Azure Repos is not a supported VCS provider. Clears reads your work items from Azure Boards and works on your code in GitHub, GitLab or Bitbucket.

Step 2: Connect Your VCS Provider (Required)​

After selecting a provider, the wizard guides you through connecting it and selecting at least one repository (or project, for GitLab) as an execution target: these are the repos the AI agent will work in. The steps are the same as in Jira mode; follow the instructions for your provider in Onboarding: Jira Ticketing Mode.

Step 3: Connect Azure DevOps​

There are two ways to connect Azure DevOps:

OptionChanges in Azure DevOps show asWho it suits
Connect as the Clears app (recommended)ClearsTeams that want the connection to keep working when people leave
Sign in with your accountThe person who signed inA quick trial with one Microsoft work account

Click Connect as the Clears app. The wizard opens the app panel, which takes you through the setup:

  1. Approve Clears in your Microsoft Entra tenant. An Entra admin who is also an admin of your Clears account clicks Approve Clears in Microsoft Entra, or you click Get a link for an Entra admin and send them the link.
  2. Choose your Azure DevOps organisation from the list, or click Type another name.
  3. Set up Clears in Azure DevOps: add Clears to the organisation, and allow it to manage its service hooks. Then click Check again.
  4. Click Finish connecting.

Steps 1 and 3 are done partly in Microsoft Entra and in Azure DevOps, and need an admin there. Connecting with the Clears App explains each of them in full: who must do what, which permissions Clears needs, and what to do when a check fails.

tip

The approval in Microsoft Entra brings you back to Settings → Integrations → Azure DevOps. You can finish connecting there, or come back to this step of the wizard to pick up where you left off.

Once connected, the step shows Connected - <your-org> as the Clears app. Click Continue.

Option B: Sign in with your account​

  1. Under Sign in with your account, click Connect
  2. Sign in with your Microsoft work account
  3. Once signed in, the step shows Signed in to Microsoft
  4. Click Continue, then choose your organisation in the next step

You can switch a user connection to the Clears app later, from Settings → Integrations → Azure DevOps (see Switching from a User Connection).

Step 4: Choose Your Organisation and Projects​

This step confirms the Azure DevOps organisation Clears works in.

  • If you connected as the Clears app, the organisation was chosen in the app panel, and the step shows it.
  • If you signed in with your account, choose the Organization from the list and click Finish connecting.

Clears works on work items tagged auto, in every project of the organisation that it can reach. To limit Clears to specific projects, use Limit to specific projects in Settings → Integrations → Azure DevOps after onboarding (see Projects).

Click Continue.

Step 5: Review the Status Mapping​

Clears maps each Azure DevOps state to a Clears status. It fills these mappings in for you from each state's category in Azure DevOps (Proposed, In Progress, Resolved, Completed, Removed).

  1. Review the table: each row shows an Azure DevOps State and the Clears status it maps to
  2. Change any mapping that doesn't fit your process. Each change is saved at once
  3. Click Continue

If the table is empty, your work items haven't synced yet. You can review the mappings later in Settings → Integrations → Azure DevOps (see Status Mapping).

Unlike Jira, there is no webhook or status setup to do in Azure DevOps: Clears registers its service hooks itself, and it doesn't need any new states in your process.

Step 6: Name Your Levels​

Clears organises work in four levels: initiative, epic, story and subtask. This step chooses what your account calls them in Clears.

For an Azure DevOps account, the names start on the Azure DevOps (Agile) preset: Epic / Feature / User Story / Task.

note

Azure DevOps' Epic is Clears' initiative, and Azure DevOps' Feature is Clears' epic. The preset follows how Clears reads your work item types, so the names you see in Clears match your Azure DevOps backlog.

  1. Keep the Azure DevOps (Agile) preset, choose Jira for Clears' own names, or edit the names to make your own
  2. For each level, set the article (a or an), the singular and the plural
  3. Click Continue. The names shown are saved, even if you didn't change them

Only admins can change the names. Other users see them read-only and can click Continue. You can change the names later in Settings → Level naming. See Naming Your Levels for the rules and for where the names are used.

Step 7: Connect Slack or Microsoft Teams (Optional)​

Clears messages people through one platform: Slack or Microsoft Teams. Choose the one your team uses; it enables notifications and interactive Q&A during story analysis. The steps are the same as in Jira mode: see Step 7 of Onboarding: Jira Ticketing Mode.

This step is optional — click Skip for now if you prefer to set it up later. Without a messaging platform, Q&A interactions happen directly on the Board.

Completing Onboarding​

After finishing all steps, the wizard marks your onboarding as complete and redirects you to the Board — the main workspace where you'll create and manage stories.

Your onboarding progress is saved automatically, so if you close the wizard mid-way, you'll resume where you left off on your next sign-in.

Next Steps​

With your account configured: