Azure DevOps

Anthara works with Azure DevOps through each person’s connection and through service hooks that send events to Anthara. One deployment works with one Azure DevOps organization.

The connection

A connection is your own sign-in to Azure DevOps through an OAuth app. To create one, see Connections.

Anthara asks for these scopes:

Scope	Why
vso.code_manage	Read repositories, push branches, and open pull requests.
vso.project	Read projects.
vso.work_write	Read and update work items.
vso.profile	Read your profile.
offline_access	Stay connected without asking you to sign in again.

Anthara uses your connection to:

• list the repositories you can import
• clone a repository when you run an assessment
• open the pull request when you activate Anthara on a repository
• read work items in a workflow’s read_data step
• give a workflow step access to Azure DevOps

In a workflow, a connection named Azure DevOps reaches the agent as the environment variable AZURE_DEVOPS_ACCESS_TOKEN.

Deployment settings

Two settings are configured when Anthara is installed:

Setting	Meaning
AZURE_DEVOPS_ORG_URL	The address of your Azure DevOps organization.
AZURE_DEVOPS_WEBHOOK_SECRET	The password that each service hook sends to Anthara.

Create the service hooks

Azure DevOps sends events through service hooks. Anthara does not create them for you. An Azure DevOps project admin creates them once per project.

1. In Azure DevOps, open Project settings, then Service hooks.
2. Create a subscription and choose Web Hooks.
3. Choose the event. The table below shows which event each trigger needs.
4. Set the URL to the API route /azure-devops/webhooks. On a standard install the address is https://<your-domain>/api/azure-devops/webhooks.
5. Set basic authentication. Enter any username. Set the password to the value of AZURE_DEVOPS_WEBHOOK_SECRET.
6. Save the subscription.

Anthara checks only the password. It ignores the username.

Create one subscription for each row you need:

Azure DevOps event	Needed for
Pull request created	git.pullrequest.created
Pull request updated	git.pullrequest.updated
Build completed	build.complete
Pull request commented on	git.pullrequest.commented

Events that can start a workflow

A workflow with trigger.type: azure_devops lists the events it reacts to.

Event in the workflow YAML	When the workflow runs
git.pullrequest.created	A pull request is created.
git.pullrequest.updated	A pull request is updated.
build.complete	A build finishes with the result failed. Other results are ignored.
git.pullrequest.commented	Someone comments on a pull request and mentions @anthara.

The trigger also needs a top-level repo, written as org/project/repo or org/project/*, and a list of branches.

name: Fix failed builds
slug: fix-failed-builds
repo: acme/claims/claims-api
trigger:
  type: azure_devops
  config:
    events:
      - build.complete
    branches:
      - main
steps:
  - name: investigate
    type: ai_task
    config:
      prompt: |
        Build {{inputs.runId}} failed on {{inputs.headBranch}}. Find the cause.

For the inputs each event provides, see Triggers.

Who the run acts as

A run started by an Azure DevOps event has no person behind it. Anthara uses the Azure DevOps connection of the person who created the workflow.

This has two consequences:

• The workflow’s creator must stay connected to Azure DevOps. If they are not connected, the run fails.
• A comment the run posts looks like a comment from that person. A workflow that answers @anthara comments must never write @anthara in its own reply, or it will start itself again.

Read work items in a workflow

A read_data step with the azure_devops provider runs a WIQL query. WIQL is the query language for Azure DevOps work items.

- name: fetch-bugs
  type: read_data
  provider: azure_devops
  connection: Azure DevOps
  config:
    organization: acme
    project: claims
    query: >
      SELECT [System.Id] FROM WorkItems
      WHERE [System.WorkItemType] = 'Bug' AND [System.State] = 'New'

organization and project are required.

Pull requests from workflows

A coding_task step clones the repositories it is given, pushes a branch named anthara/<short-slug>, and opens a draft pull request through the Azure DevOps REST API.