# Azure devops

SureCloud connects to Azure DevOps to retrieve repository access controls, pipeline run history, branch protection policies, and security configuration across your Azure DevOps organisation. This allows SureCloud to verify that code repositories are protected by branch policies, that CI/CD pipelines include required security steps, and that access to DevOps resources is appropriately restricted — providing evidence for source code management and SDLC security controls.

## Authentication and setup

Azure DevOps supports OAuth 2.0 and Personal Access Tokens for API access. SureCloud uses a Personal Access Token associated with a dedicated service account within your Azure DevOps organisation.

{% stepper %}
{% step %}
**Create a dedicated service account**

In Azure Active Directory (Microsoft Entra ID), create a service account user (e.g. `surecloud-ado@yourcompany.com`) and add it to your Azure DevOps organisation with **Reader** access at the organisation level. Using a dedicated service account ensures the token remains valid independently of individual user accounts.
{% endstep %}

{% step %}
**Generate a Personal Access Token**

Log in to Azure DevOps as the service account. Navigate to **User Settings → Personal Access Tokens** and click **New Token**. Name it `SureCloud CCM`, set the expiry to 90 days (maximum recommended), and configure the following scopes: **Code (Read)**, **Build (Read)**, **Release (Read)**, **Project and Team (Read)**, **Member Entitlement Management (Read)**. Click **Create** and copy the token.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Azure DevOps → Connect**. Enter your Azure DevOps organisation URL (e.g. `https://dev.azure.com/yourorgname`), the service account username, and the Personal Access Token. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Azure DevOps Personal Access Tokens expire. SureCloud will alert you when a token is approaching expiry. Rotate the token before it expires and update it in **SureCloud → Integrations → Azure DevOps → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                               | Use Case                                                                |
| ------------------------------------------------------ | ----------------------------------------------------------------------- |
| `GET /{org}/_apis/projects`                            | Enumerate all projects in the Azure DevOps organisation                 |
| `GET /{org}/{project}/_apis/git/repositories`          | List Git repositories per project                                       |
| `GET /{org}/{project}/_apis/git/policy/configurations` | Retrieve branch policy configurations (reviewers, build validation)     |
| `GET /{org}/{project}/_apis/build/definitions`         | Enumerate pipeline definitions to confirm security steps are configured |
| `GET /{org}/{project}/_apis/build/builds`              | Retrieve build run history including result and trigger source          |
| `GET /{org}/{project}/_apis/release/definitions`       | List release pipeline definitions                                       |
| `GET /{org}/_apis/graph/users`                         | Enumerate organisation users and their group memberships                |
| `GET /{org}/_apis/securitynamespaces`                  | Retrieve security namespace definitions for access control evidence     |

## Pagination

Azure DevOps REST APIs use `continuationToken` pagination. SureCloud uses the `x-ms-continuationtoken` response header value as the `continuationToken` parameter in the next request, continuing until no continuation token is returned.

```
GET /{org}/_apis/graph/users?continuationToken=<value_from_previous_response>
```

`GET /{org}/{project}/_apis/build/builds` also supports `$top` and `$skip` for historical build queries.

## Required permissions

SureCloud requires a Personal Access Token with the following scopes:

| Scope                                | Purpose                                                |
| ------------------------------------ | ------------------------------------------------------ |
| Code (Read)                          | Access repository list and branch policy configuration |
| Build (Read)                         | Read pipeline definitions and build run history        |
| Release (Read)                       | Read release pipeline definitions                      |
| Project and Team (Read)              | Enumerate projects and team membership                 |
| Member Entitlement Management (Read) | Read user access entitlements                          |

No write, manage, or admin scopes are required.

## Polling frequency

| Data Type                           | Interval       |
| ----------------------------------- | -------------- |
| Repository list and branch policies | Every 24 hours |
| Pipeline definitions                | Every 24 hours |
| Build run history                   | Every 6 hours  |
| User and group membership           | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized or TF400813</summary>

The Personal Access Token is invalid, has expired, or the service account does not have access to the organisation. Confirm the token is valid in **Azure DevOps → User Settings → Personal Access Tokens**. If expired, generate a new token and update it in **SureCloud → Integrations → Azure DevOps → Edit Connection**.

</details>

<details>

<summary>Some projects are missing from SureCloud</summary>

SureCloud collects all projects visible to the service account. Projects with restricted visibility (private projects where the service account is not a member) will not appear. Add the service account as a Reader to any missing projects in **Azure DevOps → Project Settings → Permissions**.

</details>

<details>

<summary>Branch policies are not returned for some repositories</summary>

Branch policies are configured per-branch and per-repository. If a repository has no branch policies configured, the policies endpoint returns an empty array — this is itself a finding that the repository lacks branch protection. Confirm whether policies should be configured in Azure DevOps for that repository.

</details>

<details>

<summary>Personal Access Token is approaching expiry</summary>

Azure DevOps PATs have a maximum lifespan of 1 year. SureCloud recommends 90-day rotation. When a token is close to expiry, generate a new one with the same scopes under **Azure DevOps → User Settings → Personal Access Tokens** and update it in **SureCloud → Integrations → Azure DevOps → Edit Connection** before the old token expires.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/azure-devops.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.