# Azure DevOps Work Items
URL: https://docs.clearly-ai.com/docs/integrations/issue-trackers/azure-devops-work-items
Description: Connect Clearly AI to Azure DevOps Work Items.
Connect Azure DevOps Work Items so Clearly AI can read work items as Project sources and use work items in Workflows.

Azure DevOps Work Items is separate from [Azure Repos](https://docs.clearly-ai.com/docs/integrations/code/azure-repos). Use this page for tickets. Use Azure Repos for code repositories.

## What the integration does [#what-the-integration-does]

Clearly AI can:

* Fetch work item title, description, state, assignee, tags, comments, related work items, and attachments.
* Add comments to work items.
* Create work items.
* Assign or unassign work items.
* Add or remove tags.
* Attach Review exports to work items.
* Trigger Workflows when work items are created or updated.

<Note>
  Create the PAT from an Azure DevOps user or service account that can access the projects and work items Clearly AI should use. Use a dedicated service account for shared connections or production Workflows.
</Note>

## Create an Azure DevOps token [#create-an-azure-devops-token]

1. In Azure DevOps, open **User settings -> Personal access tokens**.
2. Click **New Token**.
3. Choose the organization Clearly AI should access.
4. Set an expiration date that matches your security policy.
5. Grant **Work Items: Read** for source ingestion.
6. Grant **Work Items: Read & Write** if Workflows should create, comment on, assign, tag, or attach files to work items.
7. Create the token and copy it. Azure DevOps shows the token only once.

## Connect in Clearly AI [#connect-in-clearly-ai]

1. In Clearly AI, open **Organization settings**, select **Integrations**, then click **Set up** on the Azure DevOps Work Items card.
2. In **Organization ID**, enter the Azure DevOps organization name from `https://dev.azure.com/<organization>`.
3. Under **Authentication**, in **Shared API Token**, paste the PAT.
4. Check **I understand** under the shared-credential notice, then click **Add workspace credential**. Clearly AI tests the credential and enables the integration only when the test passes.

## Add a work item as a source [#add-a-work-item-as-a-source]

1. Open a Project.
2. Open **Manage Sources** and click **Search Integrations**.
3. Select **Azure DevOps Work Items**.
4. Choose the Azure DevOps project.
5. Enter the work item ID, such as `12345`.
6. Save the source.

Clearly AI fetches the work item and includes it as Project context for Reviews and Chat.

## Use work items in Workflows [#use-work-items-in-workflows]

Azure DevOps Work Item Workflow support includes:

* **ADO Work Item Created or Updated** trigger, with optional tags, projects, and states.
* **Create ADO Work Item**.
* **Assign ADO Work Item**.
* **Create ADO Work Item Comment**.
* **Attach Review Export to ADO Work Item**.

To use the trigger, configure a **Service Hooks > Web Hooks** subscription in Azure DevOps for work item events. Use the Clearly AI webhook URL as the target URL. Clearly AI shows the webhook URL and secret after you save the webhook settings. The default secret header name is `X-Clearly-Webhook-Secret`.

## FAQs [#faqs]

<Accordions>
  <Accordion title="Why does the connection test fail?">
    Confirm the token is active, has not expired, and has access to the organization.
  </Accordion>

  <Accordion title="Why are projects missing?">
    Confirm the token owner can see those projects directly in Azure DevOps.
  </Accordion>

  <Accordion title="Why can't Clearly AI fetch a work item?">
    Confirm the work item ID is correct and belongs to the selected project.
  </Accordion>

  <Accordion title="Why do workflow actions fail?">
    Confirm the PAT has **Work Items: Read & Write** access.
  </Accordion>

  <Accordion title="Why isn't my Azure DevOps workflow trigger running?">
    Confirm the Azure DevOps Service Hooks subscription posts to the Clearly AI webhook URL, includes the configured secret header, and uses a work item event such as created or updated. Also check that the work item matches any tag, project, or state filters on the trigger node.
  </Accordion>
</Accordions>

## Related [#related]

* [Integrations](https://docs.clearly-ai.com/docs/integrations)
* [Workflows](https://docs.clearly-ai.com/docs/workflows)
* [Azure Repos](https://docs.clearly-ai.com/docs/integrations/code/azure-repos)