> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Azure DevOps
> Configure Azure DevOps as a source control provider for your Ona environments.
Azure DevOps is supported on [Self-Hosted Runners](/ona/runners/aws/overview). Set up the integration during runner creation or in runner settings. Self-hosted Azure DevOps instances are supported by changing the Host during setup.
Azure DevOps is not available on Ona Cloud. Creating an environment from an Azure DevOps repository there fails with: `Ona Cloud (US01) requires authentication with Source Control - the SCM integration for host dev.azure.com is not configured`.
## Configuring Azure DevOps Access
If Azure DevOps is already set up on your runner, skip to [Authorizing Azure DevOps Access](#authorizing-azure-devops-access).
### Self-Hosted Runners
For self-hosted runners (like AWS), Azure DevOps integration is configured during runner creation or in the runner settings.
There are two ways to integrate with Azure DevOps. Both can be used simultaneously:
1. **OAuth App (Recommended):** Using a Microsoft Entra ID OAuth app allows users to sign in more quickly. You'll need to set up an OAuth app within Microsoft Entra ID.
2. **Personal Access Token (PAT):** Each user will need to create a Personal Access Token. They will be provided with a deep link to do so on their first environment creation.
#### Using OAuth
OAuth requires a [Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/entra-oauth?view=azure-devops) app registration. You will set up the app in Azure, then enter its credentials in Ona.
**Step 1: Create the Entra ID app registration**
1. Go to the [Azure Portal](https://portal.azure.com) and navigate to **Microsoft Entra ID > App registrations**.
2. Click **New registration** and provide a name (e.g., "Ona Azure DevOps Integration").
3. Note the *Client ID* from the **Overview** page.
4. Note the *Issuer URL* from **Overview > Endpoints**. Use the v2.0 URL, e.g. `https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0`.
**Step 2: Configure authentication**
1. In your app registration, go to **Manage > Authentication**.
2. Ensure **Web** platform is selected and paste the callback URL from the Ona configuration dialog.
3. Enable **ID tokens** under *Implicit grant and hybrid flows*.
**Step 3: Create a client secret**
1. Navigate to **Manage > Certificates & secrets**.
2. Click **New client secret**, add a description, and set expiration as needed.
3. Copy the secret **Value** immediately (it is only shown once).
**Step 4: Configure API permissions**
Go to **Manage > API permissions** and add the following scopes:
| API | Scope | Purpose |
| --------------- | ---------------- | --------------------------------------------------------- |
| Microsoft Graph | `openid` | OpenID Connect authentication |
| Microsoft Graph | `offline_access` | Refresh tokens |
| Azure DevOps | `vso.code` | Read repositories, commits, pull requests, refs, branches |
| Azure DevOps | `vso.code_write` | Commit and push operations |
**Step 5: Prepare Azure DevOps**
1. In Azure DevOps, go to **Organization Settings > Security > Policies** and enable **Third-party application access via OAuth**.
2. Go to **Organization Settings > General** and connect your Microsoft Entra ID tenant.
**Step 6: Connect in Ona**
1. Go to **Settings → Runners** and select the runner you want to configure.
2. In the **Configure repository access** section, click **Select** next to **Azure DevOps (Entra ID)**. If other providers are already configured, click **Add a new provider** first.
3. Toggle **Enable OAuth**.
4. Enter the **Issuer URL**, **Client ID**, and **Client Secret** from the steps above. The client secret is encrypted with the runner's public key, so only the runner can read it.
5. Click **Save & Test**. This also verifies the connection to Entra ID.
#### Using Personal Access Tokens (PATs)
1. Go to **Settings → Runners** and select the runner you want to configure.
2. In the **Configure repository access** section, click **Select** next to **Azure DevOps**. If other providers are already configured, click **Add a new provider** first.
3. Toggle **Enable Personal Access Token**.
4. Click **Save**.
## Authorizing Azure DevOps Access
### Using OAuth (Microsoft Entra ID)
1. When creating your first environment, you will be prompted to authorize. Click **Connect**. A new window opens directing you to Microsoft Entra ID to authorize the OAuth app with the scopes configured above.
2. After authorizing, close the window. You should see a confirmation that Azure DevOps (Entra ID) is connected.
### Using Personal Access Tokens (PATs)
1. When creating your first environment, you will be asked to authorize the new application. Select *Provide a Personal Access Token*.
* Follow the instructions of the Azure documentation to create a PAT
* The name of the token and all required scopes are pre-set.
* By default, the token is valid for 30 days, but you can change the duration if needed.
2. After creating the token, return to the dialog and paste the token.
3. The environment will now be created using the provided token.