What it enables
Sign in with Microsoft
Connect your Azure DevOps account through the device code flow, with no password handling inside the app.
Browse repositories
List Git repositories across every organization and project your account can reach.
Encrypted tokens
Access and refresh tokens are encrypted at rest with the operating system keychain and never exposed to the renderer.
Automatic refresh
Orkestral refreshes the access token in the background while a refresh token is available.
Requirements
- A Microsoft work or school account with access to at least one Azure DevOps organization.
- The repositories you want to use must live in Azure Repos (Git). Orkestral only lists repos that expose a clone URL.
- A working operating system keychain so Orkestral can encrypt tokens. On macOS this is the Keychain, on Windows the Credential Manager, on Linux a Secret Service provider. If encryption is unavailable, the connection fails with an error.
- An internet connection to reach
login.microsoftonline.com,app.vssps.visualstudio.com, anddev.azure.com.
Orkestral requests the scopes
user_impersonation (on the Azure DevOps resource) and offline_access. The offline_access scope is what lets Orkestral obtain a refresh token and keep your session alive.How to connect
Open the integration
Go to the integrations or settings area and choose Azure DevOps, then start the connection.
Start the device flow
Orkestral requests a device code from Microsoft and shows you a short user code plus a verification link.
Approve in the browser
Open the verification URL (Orkestral can open it for you), sign in with your Microsoft account, and enter the user code. Approve the requested permissions.
Wait for confirmation
Orkestral polls Microsoft until you approve. When the flow returns
authorized, your account details and organizations appear in the app.Device flow states
While you complete the browser step, Orkestral polls Microsoft and reacts to each state it returns.| State | Meaning |
|---|---|
pending | You have not approved yet. Orkestral keeps polling. |
slow_down | Microsoft asks Orkestral to poll less often. The interval increases automatically. |
expired | The user code timed out. Start the connection again. |
denied | You declined the request or access was denied. |
authorized | Sign in succeeded. Your account and organizations are saved. |
Configuration options
The integration works with built-in defaults. The following environment variables let you point Orkestral at a different Microsoft Entra (Azure AD) tenant or application registration, which is useful for single-tenant or enterprise setups.The Microsoft Entra tenant used for the authority URL (
https://login.microsoftonline.com/<tenant>). Use common for multi-tenant sign in, or a specific tenant ID to restrict sign in to one directory.The application (client) ID used for the device code flow. Override this to use your own app registration.
What gets stored
When you connect, Orkestral saves a single Azure DevOps account record. The public, non secret fields you can see in the app are:| Field | Description |
|---|---|
displayName | Your name, read from the ID token. |
email | Your sign in name (preferred_username) or email. |
tenantId | The tenant ID the token was issued for. |
scope | The OAuth scopes granted. |
connectedAt | When the account was first connected. |
expiresAt | When the current access token expires. |
organizations | The Azure DevOps organizations linked to your account. |
How repository listing works
When you list repositories, Orkestral:- Gets a valid access token, refreshing it first if it expires within about 90 seconds.
- Determines which organizations to query. It uses a specific organization if you pass one, otherwise the organizations saved on your account, otherwise it discovers them from your profile.
- For each organization, lists projects, then lists the Git repositories in each project.
- Returns only repositories that have a clone URL, sorted by their full name (
organization/project/repo).
Discovery walks every organization and project you can access, so listing can take a moment on large accounts. Repositories without a usable remote URL are skipped.
Disconnecting
Disconnecting deletes the stored Azure DevOps account, including the encrypted access and refresh tokens. After disconnecting, you need to run the device flow again to reconnect. Sources you already added stay configured, but Orkestral can no longer fetch fresh data for them until you reconnect.Capabilities and limits
- Orkestral reads repository metadata for browsing and adding sources. It acts with your own Azure DevOps permissions through
user_impersonation. - Only Azure Repos (Git) repositories are listed. TFVC repositories and repos without a clone URL do not appear.
- The session stays alive automatically while a refresh token is present. If the access token expires and no refresh token exists, you are asked to connect again.
- Token encryption depends on the operating system keychain. In environments where it is unavailable, connecting and reading tokens fail.
Troubleshooting
Encryption not available
Encryption not available
Orkestral could not reach the operating system keychain to encrypt or decrypt tokens. Make sure your keychain or credential store is unlocked and available, then try connecting again. On Linux, confirm a Secret Service provider (such as GNOME Keyring) is running.
The user code expired before I approved
The user code expired before I approved
The device code is short lived. Start the connection again to get a new code, then approve it promptly in the browser.
Session expired. Connect again.
Session expired. Connect again.
Your access token expired and no refresh token was stored, or the refresh failed. Disconnect and run the device flow again to get a new session.
No organizations or repositories appear
No organizations or repositories appear
Confirm your account belongs to at least one Azure DevOps organization and that the repositories are Git based. Orkestral discovers organizations from your profile, so make sure your profile is accessible. If you use a single tenant setup, verify
ORKESTRAL_AZURE_TENANT_ID points to the correct directory.Sign in is declined or access denied
Sign in is declined or access denied
The flow returned
denied. Re-run the connection and approve every requested permission. If your organization enforces conditional access policies, an administrator may need to allow the app registration.A repository I expect is missing
A repository I expect is missing
Orkestral skips repositories that do not expose a clone URL and only lists Azure Repos (Git). Check that the repo exists under a project you can access and that it is a Git repository.
Related
Sources
Add connected repositories as sources for your agents.
Integrations
See the other providers you can connect to Orkestral.