Permissions
Extension scopes
| Scope | Why it is needed | Used by |
|---|---|---|
vso.wiki_write |
Read Wiki pages (including the persona pages of an earlier version, for a one-time import); save edits (version-checked) and create pages (create-only) after the user confirms | Hub, documentation assistant, Ask the Wiki |
vso.work_write |
Read and query work items, types, area and iteration paths; create or update work items (also a connecting Epic and its links), create iterations and add them to a team's sprints, each after the user confirms | Hub, Ask about Work Items, Ada on work items, Create Sprint Schedule |
vso.project |
List projects and teams, read the process template | Hub |
vso.code |
Read-only search of merged and active pull requests, pull-request metadata (title, description, branches, file paths, commits, linked work items), the repository list, and repository files for architecture documentation, debates and pull-request reviews. Reviews post nothing to the pull request | Pull-request docs, organization settings, Generate Project Documentation (architecture), Debate Architecture, Review a Pull Request |
vso.build |
Read-only classic (designer) build pipeline definitions, for the deployment view | Generate Project Documentation (architecture) |
vso.release |
Read-only classic release pipeline definitions and their stages, for the deployment view | Generate Project Documentation (architecture) |
Not requested: code write, build or release execution, identity management, security management, organization administration. Pipelines are only read, never created or changed.
The extension never asks for a personal access token. Azure DevOps calls from the extension run with the signed-in user's own permissions, so there users can only read or change what they could anyway. The exceptions are below. Extension data (the backend configuration and project templates) is the extension's own storage and needs no scope.
Exceptions: features that read with the backend's own access
Two features answer from more than the asking user may be able to open, on purpose:
- Ask with search: it searches and reads the projects and repositories that administrators chose under Search and diagnosis.
- Diagnose a Ticket: it does the same, plus the log sources administrators connected.
Both read with the backend's own identity, not the user's. A support agent, for example, needs answers from every board, every repository and the monitoring system without access to each of them. So anyone allowed to use these two features can get answers, with quotes, from everything administrators chose for them. Administrators decide who that is: choose the projects, repositories and log sources with that in mind, and limit who can use the features with the access settings.
The jobs that administrators set up also run with the backend's own identity, as SECURITY.md and DATA-HANDLING.md describe for each:
- Repository Documentation;
- Code with Ada;
- pull-request checks;
- routines;
- the Mockup Designer's reading of your applications' code.
The hub is a top-level group in the project sidebar (ms.vss-web.project-hub-groups-collection); the work-item form group is named "Ada". Neither needs a scope.
Organization-level actions
| Action | Who | Notes |
|---|---|---|
| Install the extension | Organization or project collection administrators (Marketplace) | Re-approval is required when scopes change |
| Configure the backend | Project Collection Administrators (admin page) | See the limitation in ADMIN-CONFIGURATION.md |
| Use AI features | Users allowed by the organization's backend (tenant, organization, users, groups, app role) | Enforced by the backend |
| Write Wiki pages or work items | Users with the corresponding Azure DevOps permission | Always after explicit confirmation |
Normal features need no administration permissions.
Administrators can narrow this further under Organization settings > Ada AI > Access (backend 1.64.0): limit tabs and single quick actions to Azure DevOps teams and groups, and turn on Read-only Ada, under which Ada changes nothing in Azure DevOps for anyone: the extension and the backend both refuse every change. The extension's scopes stay as listed above, since Azure DevOps grants them per extension.
Backend permissions (reference deployment)
- Backend app identity: Key Vault Secrets User, read-only, on the needed secrets.
- With
STATE_STORE=blobit also has Storage Blob Data Contributor on its state container (pull-request proposals, MCP proposals, architecture jobs, personas). - In Azure DevOps (pull-request checks,
ADO_AUTH_MODE) it has Basic access, Read on the enabled repositories and Wikis, and Contribute to pull requests. It also reads the signed-in user's group memberships to recognize Project Collection Administrators as backend administrators, and, with access by tab, to check the teams and groups a tab is limited to; for administrators choosing them, it lists the organization's teams and searches its groups. Organization members can read memberships, teams and groups by default; access by tab needs no other permission and no new extension or Entra scope. - With Code with Ada (
CODE_AGENT_ENABLED) it also has, on the repositories administrators enable only: Read, Contribute, Create branch and Contribute to pull requests; and on the pipelines that validate those pull requests, View builds (to read what failed) and Queue builds (a draft pull request runs its pipelines only when asked; without this Ada publishes the draft so that they run). It creates branches underada/code/, pushes to them after a person approved the plan, and opens pull requests with the administrators' reviewer groups. It never pushes to a target branch, never force-pushes, never bypasses branch policies and never completes a pull request. No extension scope or Entra permission is added. - With Repository Documentation (
REPO_DOCS_ENABLED) it also has, on the repositories administrators enable only: Read, Contribute, Create branch and Contribute to pull requests. A run first asks Azure DevOps whether it has these, with read-only calls about its own identity. It creates branches underada/docs/, pushes to them and opens pull requests into the default branch with the administrators' reviewer groups; with dev documents on, also branches underada/dev-docs/and pull requests into each repository's dev branch. It never pushes to a default branch, never force-pushes and never bypasses branch policies. It completes no pull request itself: dev documents with no reviewer group in the settings are set to complete by themselves once the dev branch's policies pass, so a policy that wants a person still waits for one. It writes as itself, not on a user's behalf, so the pull requests show the backend's identity as their author. No extension scope or Entra permission is added.
- With
- No separate sign-in (
AUTH_MODE=azure-devops): no backend identity and no app registration. When a session starts, the backend receives the user's Azure DevOps access token, with the extension's permissions above, and uses it once to ask Azure DevOps who the user is; it is neither stored nor logged. - Coding tools through Ada's MCP server: by default the developer's tool sends their own Azure DevOps access token, or a personal access token that reads Code, Work Items and Wiki. No app registration and no backend identity; the backend only reads with the token, and doesn't keep it.
- Microsoft sign-in (
AUTH_MODE=entra), and MCP clients that sign in with Entra ID: no backend identity. Delegated, read-only Azure DevOps permissions on the backend's Entra app registration:vso.profile(membership check at sign-in),vso.wiki,vso.workandvso.code(MCP tools acting as the signed-in user). Notuser_impersonation: the backend never writes to Azure DevOps on a user's behalf. - Secret administrators: Key Vault Secrets Officer.
- Deployers: resource-group Contributor.
No identity gets Owner or Key Vault Administrator for runtime use.
