AdaDocsAda AI for Azure DevOpsTry the demo

Deploy the backend

Ada's backend runs in your Azure subscription, with your AI provider and credentials. It is published as a private container image; you don't build anything:

adavalorconsulting.azurecr.io/ada-backend:<version>

Rather not run it yourself? With Ada as a managed service, Valor Consulting runs your backend for you.

Pulling the image needs your organization's registry credentials, a user and a password. Get them in Ada: Organization settings > Ada AI > Backend settings > Set up a backend > Get access to the backend image (organization administrators). If your Ada doesn't show it yet, ask at contact@valor-co.com and name your Azure DevOps organization. Keep them secret; they are for your organization only.

There are three ways to set it up: the deployment form in the Azure portal; the setup script in Azure Cloud Shell, which you can read before it runs and which also takes care of the steps in Azure DevOps; or by hand.

Quick start: the deployment form

  1. Get the registry user and password in Ada, as above.
  2. Open the deployment form in the Azure portal. Choose a subscription and a resource group, then fill in:
    • the backend's name and your Azure DevOps organization;
    • Ai Provider and its key: anthropic needs only your Anthropic API key (the address stays empty: the form fills in https://api.anthropic.com); foundry (Claude in Microsoft Foundry) the resource's address, https://<resource>.services.ai.azure.com/anthropic, its key and your deployment's name; openai-compatible (for example Azure OpenAI) the chat completions address, the model and the key's header;
    • Read Code, Code With Ada, Web Search, Ai Search, Grafana Url or Create Grafana, Mockup Browser and Pull Request Checks, if you want those features from the start (the table below);
    • the registry user and password;
    • Tags, only if your organization's Azure Policy asks for them, for example {"CostCenter": "1234"}.
  3. Select Review + create. When the deployment is done, its Outputs show the backend's address, the name of its identity, the address for the pull-request service hook and the name of the Key Vault.
  4. In Azure DevOps: Organization settings > Users > Add users, search for that identity (<app>-identity) and give it the access level Basic. Ada then knows your organization's administrators (the members of Project Collection Administrators), and the backend can read what its features need.
  5. In Ada: Organization settings > Ada AI > Backend settings, enter the address, select Test connection and save. Then open Setup, the next tab: it shows what is on and what each other feature still needs, and checks that Azure DevOps accepts the backend's identity.

The form creates an App Service plan (B1 unless you choose another size), the App Service running Ada's backend (with Web Search, SearXNG beside it in a second container), a Key Vault holding your AI provider's key, the backend's session key, the key that seals connection secrets, the secret of the pull-request service hook (pr-docs-hook-secret) and, with Web Search, SearXNG's (searxng-secret), a storage account without account keys for what must survive restarts, and a managed identity that reads those secrets, writes that storage and is the backend's own identity in Azure DevOps. Users sign in with their Azure DevOps account, and so do their coding tools (Ada in Your Coding Tool); no app registration is needed. You need Owner, or Contributor and User Access Administrator, on the resource group.

On the form What it turns on What it means
Always Everything that works on Wiki pages and work items, Design Requirements, Update the Wiki, Access (by tab and quick action, Read-only Ada), sprint documents and Ada in Your Coding Tool With openai-compatible, Ada answers and writes; her agents (Diagnose a Ticket, the Mockup Designer, Code with Ada) need Claude.
Read Code Project documentation from the code, Repository Documentation (Check and Generate), Review a Pull Request, Debate Architecture, How It Works Today, Delight Check and the Mockup Designer The code they read goes to your backend and to your AI provider. Repository Documentation and the Mockup Designer read with the backend's identity: give it Read on the repositories you enable, and for Repository Documentation also Contribute, Create branch and Contribute to pull requests.
Code With Ada Code with Ada, for organization administrators and the teams they allow Needs Claude (anthropic or foundry). It writes to branches of its own and opens pull requests, and your pipelines run its code.
Web Search Web search: questions can search the web when the Wiki doesn't answer them, or when the user asks; each user turns it on in Ada's settings SearXNG, a free metasearch engine, runs in a second container beside the backend and gets only its own secret, never the backend's keys. Only the question leaves the backend, without user information; search engines see the App Service's address. More.
Ai Search Ask with search and Diagnose a Ticket, and with them Connections Azure AI Search (Basic, about USD 74 a month) keeps the backend's indexes of your Wikis and work items, and an Azure OpenAI account turns their text into vectors with text-embedding-3-small, paid per use; its key goes straight into the Key Vault. Embeddings Location must offer that model, and Embeddings Deployment says where it runs: Standard in that region, DataZoneStandard in its data zone (the EU or the US). Search Projects, optional, names the projects to index, separated by commas: the backend starts with them until an administrator chooses others in Ada. Your content goes to both, in your subscription.
Grafana Url or Create Grafana Logs and traces for Diagnose a Ticket and Ask Grafana Url connects your Azure Managed Grafana: give the backend's identity the role Grafana Viewer on it. Create Grafana creates one (Standard, roughly USD 70 a month plus each person who signs in, in Grafana Location), which the backend reads: give its own identity Monitoring Reader on what it should read, and yourself Grafana Admin to open it.
Mockup Browser The Mockup Designer's browser, which opens your test environments create: a Playwright server in a third container beside the backend, which only the backend reaches; it needs plan B2 or larger, so B1 becomes B2. connect: your own Playwright server, at Playwright Server (and Playwright Token, if something in front of it asks for one), both kept in the Key Vault. Turns the Mockup Designer on too.
Pull Request Checks Automatic pull-request documentation checks When a pull request merges, Ada proposes Wiki updates for approval. Each project needs the pull-request service hook (below).

The form can't give roles outside its resource group or change Azure DevOps: the Grafana roles above, the backend's identity in your organization (step 4) and the service hooks (below) are yours to add. The setup script adds them all.

With the Azure CLI instead (it asks for the key and the password):

az deployment group create --resource-group "<resource-group>" --template-uri "https://adadocs.valor-co.com/deploy/backend.json" `
  --parameters appName="<app>" organization="<organization>" registryUsername="<registry-user>"

With foundry or openai-compatible, add aiProvider="<foundry or openai-compatible>" aiProviderBaseUrl="<address of your resource>" aiProviderModel="<deployment>". The features take webSearch=true, aiSearch=true, grafanaUrl="<address>" or createGrafana=true, mockupBrowser=create and pullRequestChecks=true.

Routines that start when a pull request merges. The form creates the secret Azure DevOps sends with each pull-request event. In each project that has such a routine, add the service hook: Project settings > Service hooks > + > Web Hooks, event Pull request updated, the address from the output pullRequestHookUrl, and the HTTP header x-ada-hook-secret:<value>, where the value is the secret pr-docs-hook-secret in the Key Vault the output keyVault names (Key Vault > Secrets, or az keyvault secret show --vault-name "<key-vault>" --name pr-docs-hook-secret --query value -o tsv). Running the form again renews the secret: enter the new value in each service hook.

Running the form again on the same resource group applies the form's settings anew: settings you added by hand on the App Service are removed (note them first), each feature stays only with its field on, users sign in once more, because the session key is renewed, and administrators enter their connections' secrets again, because the key that seals them is renewed too. The pull-request hook's secret is renewed as well: enter the new value in each service hook. The setup script, run again, keeps those secrets: use it to turn on a feature later. To move to a newer backend version, use Updating instead.

Quick start: a script you can read first

The setup script does what the deployment form does, and the steps in Azure DevOps after it: it adds the backend's identity to your organization and, if you ask, gives it access to the projects you name and adds the pull-request service hook to them. With -AllFeatures it sets up everything Ada offers in one go, web search, Azure AI Search, Grafana and the Mockup Designer's browser included, and gives the roles the form leaves to you. It runs in Azure Cloud Shell, in Bash or PowerShell, as you, and changes nothing until it has shown you its plan, with what it costs, and you have typed yes. The same script later updates the backend (-Update, see Updating) and removes it (-Remove).

It is two plain-text files, written to be read before they run:

The script downloads nothing and runs no other code. It talks to Azure (with -Grafana, also to Microsoft Graph, to find your own ID for the Grafana Admin role), to your organization in Azure DevOps and to your backend, always with your own sign-in. The one thing it sends to Valor Consulting is the registry user and password, to Valor Consulting's registry: before anything changes, it checks that they work and that the images are there, as App Service does when it pulls them, and downloads nothing. You type your AI provider's key, the registry password and, with your own Playwright server, its address at hidden prompts: they don't show on screen or in your command history, and they reach Azure through a temporary file only you can read, which the script deletes right away.

  1. Get the registry user and password in Ada, as above.

  2. Open Azure Cloud Shell, in Bash or PowerShell, and download the two files into a folder of their own:

    mkdir ada-setup; cd ada-setup
    curl -fsSL --remote-name-all https://adadocs.valor-co.com/deploy/setup-ada-backend.ps1 https://adadocs.valor-co.com/deploy/backend.bicep; chmod +x setup-ada-backend.ps1
    

    Then check them against the published checksums, below the line: sha256sum says OK or FAILED for each, and when either differs, the line deletes both. The lines on Ada's Set up a backend card download and check the version that Ada was built with in the same way.

    printf '%s  %s\n' 527eaf445914baf87fe5449394452a71a8f7a021c4551c15b97a6d614d08f2b5 setup-ada-backend.ps1 10d93839c588a91c066c6287c09945c03c6b58deccb6a6226115bc6693e2de0d backend.bicep | sha256sum -c || rm -f setup-ada-backend.ps1 backend.bicep
    
    527eaf445914baf87fe5449394452a71a8f7a021c4551c15b97a6d614d08f2b5  setup-ada-backend.ps1
    10d93839c588a91c066c6287c09945c03c6b58deccb6a6226115bc6693e2de0d  backend.bicep
    

    Each version of the two files also stays on AdaDocs at its own address, https://adadocs.valor-co.com/deploy/kit-<id>/, which Ada's lines use: a version your security team approved stays the one you download.

  3. Read them in Cloud Shell's editor (code setup-ada-backend.ps1 and code backend.bicep), or have your security team read them. The script shows the same two checksums each time it starts, and sha256sum * (Get-FileHash * outside Cloud Shell) shows them for any copy.

  4. Preview what it would do. It runs every check and shows its plan, and changes nothing; when the resource group exists already, Azure's own check and preview of the template are part of it:

    ./setup-ada-backend.ps1 -Organization <organization> -Projects "<project>,<project>" -AllFeatures -WhatIf
    

    The backend is then ada-<organization>, in the resource group rg-ada, in westeurope, as Ada suggests: -AppName, -ResourceGroup and -Location choose others, and the plan names all three. Leave out -AllFeatures for a backend with only what every backend has, or name the features you want instead (the table below).

  5. Run the same command without -WhatIf. The script checks again and, when you can use several subscriptions, asks which. When the resource group exists, Azure has checked the template against your organization's Azure Policy by then; for a new resource group, Azure checks it right after creating the group, before anything else. Then the script shows its plan, asks for the registry password, which it checks with the registry straight away, and for your AI provider's key, and starts when you type yes. It takes about 5 to 10 minutes, prints each command before it runs it, shows each resource as Azure finishes it and, once a minute, what it is still waiting for, and ends with what is left.

  6. Open the link the script ends with: Ada's Backend settings, with the backend's address filled in and its connection tested. Select Save configuration. (Or enter the address under Organization settings > Ada AI > Backend settings yourself, select Test connection and save.) Then open Setup, the next tab.

Running it again. Run the same line again, with the options you want now, to turn on a feature later or to finish a setup that stopped. For a backend that exists, the script deploys the template again and keeps the secrets its first run generated: users stay signed in, the secrets of Ada's connections stay readable, and the pull-request hooks keep theirs, unless a new hook needs a new secret (then the script gives it to all of them). It reuses the registry password the backend has while the registry accepts it, and Enter keeps your AI provider's key. -RenewSecrets renews the secrets instead, as running the form again does. If an earlier try left a deleted Key Vault or Azure OpenAI account under a name the template needs (Azure keeps them for 7 and 2 days), the plan says so, and the script purges it and deploys again.

Option What it does
-AllFeatures Everything Ada offers: -ReadCode, -CodeWithAda (with Claude), -WebSearch, -AiSearch, -Grafana, -MockupBrowser (unless -PlaywrightServer) and -PullRequestChecks.
-Projects "Web Shop,Payments" Gives the backend's identity access to these projects, for the features that work with it: a Reader (their repositories, Wikis and work items), or a Contributor with -ReadCode or -CodeWithAda, whose features push branches, open pull requests and queue builds there. Without it, the identity has no access to projects.
-PullRequestHooks Adds the pull-request service hook, with its secret, to each project in -Projects, for routines that start when a pull request merges. -PullRequestChecks adds it too.
-ReadCode, -CodeWithAda, -WebSearch, -PullRequestChecks Turn on what Read Code, Code With Ada, Web Search and Pull Request Checks turn on in the form (the table above).
-AiSearch Ask with search and Diagnose a Ticket, as Ai Search in the form. The script finds the region nearest yours that offers the embeddings model, and how it can run there. With -Projects, the backend indexes those projects (the first 20) right after the setup, until an administrator chooses others in Ada.
-Grafana, -GrafanaName Logs and traces: connects the Azure Managed Grafana your subscription has (-GrafanaName chooses one when there are several), with Grafana Viewer for the backend's identity, or creates one in the region nearest yours that offers it, with Monitoring Reader on the subscription for its own identity and Grafana Admin for you.
-MockupBrowser, -PlaywrightServer The Mockup Designer's browser: -MockupBrowser creates a Playwright server beside the backend, on plan B2 at least; -PlaywrightServer connects yours, and the script asks for its address (and a token, if something in front of it asks for one) at hidden prompts.
-AiProvider, -AiBaseUrl, -AiModel, -AiAuthHeader Another AI provider, as in the form: foundry or openai-compatible, with your resource's address and your deployment's name; -AiAuthHeader only for openai-compatible. The default, anthropic, needs only the key.
-Subscription The subscription, by name or ID. Without it, when you can use several, the script lists them and asks, suggesting one in your organization's Microsoft Entra tenant, where the backend's identity can join the organization.
-Tags CostCenter=1234,Owner=it-team Tags for the resource group and every resource, when your organization's Azure Policy asks for them.
-RegistryUser The registry user, when Ada shows one other than org-<organization>.
-Sku The App Service plan's size: B1 (the default), B2, B3, P0v3 or P1v3.
-SkipAzureDevOps Changes nothing in Azure DevOps: the script sets up Azure and ends with the steps in Azure DevOps for an administrator.
-RenewSecrets For a backend that exists: renews the secrets its setup generated rather than keep them. Users sign in once more, administrators enter their connections' secrets again, and the script gives the pull-request hooks that call the backend the new hook secret.
-Update, -Version Runs another version of the backend in each of its containers, with the registry password it has: see Updating.
-Remove Removes the backend and what the setup made for it: below.

You need Owner, or Contributor and User Access Administrator, on the resource group (on the subscription, if the script creates the resource group). The steps in Azure DevOps need an organization administrator (Project Collection Administrators), and an organization that uses the subscription's Microsoft Entra tenant: Azure DevOps takes a managed identity only from its own tenant. Without either, the script sets up Azure and ends with the steps in Azure DevOps for someone who can take them. Like any user with Basic access, the backend's identity counts toward your organization's Basic users. A Grafana's Monitoring Reader on the subscription needs Owner or User Access Administrator there; without it, the script says who should add it.

What it costs. Mostly the App Service plan (B2 with the browser); with -AiSearch, Azure AI Search Basic (about USD 74 a month) and the embeddings, per use; with a new Grafana, Azure Managed Grafana Standard (roughly USD 70 a month plus each person who signs in). The plan shows these before you type yes; Azure's pricing for your region is what counts.

Removing it. ./setup-ada-backend.ps1 -Remove -AppName <app> removes what the setup made for the backend, and only that: its resources, as the template's deployments in the resource group name them (the resource group itself, when nothing else is in it), the roles it gave outside the resource group, and in Azure DevOps the pull-request hooks that call it and its identity. It purges the Key Vault and the Azure OpenAI account as well, so nothing of them is kept and their names are free again. It finds the backend in your subscriptions, shows its plan first, and starts only when you type the backend's name. This can't be undone: the backend's settings, jobs and proposals go with it.

For a record of the run in PowerShell, run Start-Transcript first: it keeps each command the script ran, never the secrets. The script also runs on your own computer, in PowerShell with the Azure CLI signed in (az login). With -AllFeatures, the optional sections below are set up as well; what is left are your administrators' choices in Ada, such as the projects to index and the repositories Ada may change, which the script lists at the end.

In Ada. An organization administrator finds this script under Organization settings > Ada AI > Backend settings > Set up a backend, after Get access to the backend image: with your organization and its projects filled in and everything Ada offers chosen, the backend's name, resource group, region, features and the Mockup Designer's browser to change, and both steps ready to copy, for Cloud Shell's Bash or PowerShell.

By hand

The rest of this guide sets the backend up step by step, for a Microsoft sign-in, other settings and the optional features. It deploys the backend on Azure App Service for Containers, with secrets in Azure Key Vault and a managed identity. About 30 minutes; you need Contributor and User Access Administrator (or Owner) on a resource group, and the right to create an app registration in Microsoft Entra ID.

How the parts connect:

To see the published versions:

az acr repository show-tags --name adavalorconsulting --repository ada-backend --username "<registry-user>" --password "<registry-password>" -o table

Replace the placeholders in the commands: <version> (the newest in that list), <registry-user> and <registry-password>, <resource-group>, <location>, <app> (globally unique; the backend URL becomes https://<app>.azurewebsites.net), <plan>, <key-vault>, <tenant-id>, <client-id>, <organization> (the name in https://dev.azure.com/<organization>). The commands are for PowerShell with the Azure CLI.

1. Register the backend in Microsoft Entra ID

Users sign in to the backend with their work account.

  1. In the Microsoft Entra admin center, create an app registration (single tenant), for example "Ada backend". Note the Application (client) ID (<client-id>) and Directory (tenant) ID (<tenant-id>).
  2. Add a Web redirect URI: https://<app>.azurewebsites.net/auth/callback.
  3. Create a client secret. You store it in Key Vault in step 3; don't save it anywhere else.
  4. Under API permissions, check that Microsoft Graph openid and profile (delegated) are listed, and add Azure DevOps delegated permissions vso.profile, vso.wiki, vso.work and vso.code (all read-only; not user_impersonation). The backend uses vso.profile once at sign-in to check that the user belongs to your Azure DevOps organization, and the others only for the MCP server, acting as the signed-in user.
  5. Select Grant admin consent for . This needs a Cloud Application Administrator, Application Administrator or Global Administrator. Without it, users are asked for admin approval when they sign in.

Optional: define an app role (for example Ada.User), assign it to users or groups, and set REQUIRED_APP_ROLE in step 4 to limit who may use Ada.

2. Create the App Service and the Key Vault

az login
az group create --name "<resource-group>" --location "<location>"
az appservice plan create --name "<plan>" --resource-group "<resource-group>" --is-linux --sku B1
az webapp create --name "<app>" --resource-group "<resource-group>" --plan "<plan>" `
  --container-image-name "adavalorconsulting.azurecr.io/ada-backend:<version>" `
  --container-registry-url "https://adavalorconsulting.azurecr.io" `
  --container-registry-user "<registry-user>" --container-registry-password "<registry-password>"
az webapp update --name "<app>" --resource-group "<resource-group>" --https-only true
az webapp config set --name "<app>" --resource-group "<resource-group>" --min-tls-version 1.2 --ftps-state Disabled --always-on true
$appId = az webapp show --name "<app>" --resource-group "<resource-group>" --query id -o tsv
az resource update --ids "$appId/config/web" --set properties.healthCheckPath=/api/health

az webapp identity assign --name "<app>" --resource-group "<resource-group>"
$principal = az webapp identity show --name "<app>" --resource-group "<resource-group>" --query principalId -o tsv
az keyvault create --name "<key-vault>" --resource-group "<resource-group>" --location "<location>" --enable-rbac-authorization true
$kvId = az keyvault show --name "<key-vault>" --query id -o tsv
az role assignment create --role "Key Vault Secrets User" --assignee-object-id $principal --assignee-principal-type ServicePrincipal --scope $kvId
$me = az ad signed-in-user show --query id -o tsv
az role assignment create --role "Key Vault Secrets Officer" --assignee-object-id $me --assignee-principal-type User --scope $kvId

App Service keeps the registry credentials in its settings and uses them for every pull. Role assignments can take a few minutes to apply.

3. Store the secrets

Type each value at the prompt, so it never appears in your command history:

function Set-AdaSecret($name) {
  $secure = Read-Host -AsSecureString "Value for $name"
  $plain = [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure))
  az keyvault secret set --vault-name "<key-vault>" --name $name --value $plain --output none
}
Set-AdaSecret "ai-provider-api-key"     # your AI provider's key
Set-AdaSecret "entra-client-secret"     # the client secret from step 1
Set-AdaSecret "session-signing-key"     # 32+ random characters, see below

For the session signing key, generate a value and paste it at the prompt:

$bytes = New-Object byte[] 48; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes); [Convert]::ToBase64String($bytes)

4. Configure the backend

$kv = "https://<key-vault>.vault.azure.net/secrets"
az webapp config appsettings set --name "<app>" --resource-group "<resource-group>" --output none --settings `
  "WEBSITES_PORT=3001" `
  "AUTH_MODE=entra" `
  "PUBLIC_BASE_URL=https://<app>.azurewebsites.net" `
  "ENTRA_TENANT_ID=<tenant-id>" `
  "ENTRA_CLIENT_ID=<client-id>" `
  "ENTRA_CLIENT_SECRET=@Microsoft.KeyVault(SecretUri=$kv/entra-client-secret/)" `
  "SESSION_SIGNING_KEY=@Microsoft.KeyVault(SecretUri=$kv/session-signing-key/)" `
  "ALLOWED_ORGANIZATIONS=<organization>" `
  "ALLOWED_ORIGINS=https://valorconsulting.gallerycdn.vsassets.io" `
  "AI_PROVIDER=openai-compatible" `
  "AI_PROVIDER_BASE_URL=<chat-completions URL of your provider>" `
  "AI_PROVIDER_MODEL=<model or deployment name>" `
  "AI_PROVIDER_AUTH_HEADER=<header your provider expects, e.g. api-key or authorization>" `
  "AI_PROVIDER_API_KEY=@Microsoft.KeyVault(SecretUri=$kv/ai-provider-api-key/)"
az webapp restart --name "<app>" --resource-group "<resource-group>"

5. Verify

Invoke-RestMethod "https://<app>.azurewebsites.net/api/health"   # status "healthy" and the backend version
Invoke-RestMethod "https://<app>.azurewebsites.net/api/ready"    # succeeds when the AI provider is configured

In the portal, App Service > Settings > Environment variables shows a green Key Vault Reference status for each secret.

6. Connect your Azure DevOps organization

An organization administrator (Project Collection Administrators) opens Ada in any project, selects Ada settings > Admin settings, then Backend settings, enters https://<app>.azurewebsites.net, selects Test connection and saves. Each user then confirms the backend once and signs in. Details: ADMIN-CONFIGURATION.md.

Updating

New backend versions are published as new image tags; the start of this guide shows how to list them. Pin a version, and move to a new one deliberately. When your backend is older than the newest release, Ada's header shows an Update button: it lists what each newer version brings, marks important fixes, and gives these lines for Azure Cloud Shell (Bash or PowerShell), with your App Service's name and the new version filled in:

mkdir ada-setup; cd ada-setup
curl -fsSL --remote-name-all https://adadocs.valor-co.com/deploy/setup-ada-backend.ps1 https://adadocs.valor-co.com/deploy/backend.bicep; chmod +x setup-ada-backend.ps1
./setup-ada-backend.ps1 -Update -AppName <app> -Version <new-version>

The setup script finds the backend in your subscriptions and runs the new version in each of its containers: the backend, and SearXNG and the Playwright server when it has them. It pulls them with the registry password the backend already has; only when the registry no longer accepts it does it ask for a new one from Set up a backend in Ada, at a hidden prompt. Everything else stays as it is: the settings, the secrets and each container's own settings. It checks that the new version is in the registry before anything changes, shows its plan, waits until the backend answers with the new version, and names the version it ran before: -Version <that version> goes back. Without -Version, it runs the version of the backend.bicep beside it.

By hand, for a backend in one container:

az webapp config container set --name "<app>" --resource-group "<resource-group>" --container-image-name "adavalorconsulting.azurecr.io/ada-backend:<new-version>"
az webapp restart --name "<app>" --resource-group "<resource-group>"

With web search or the Playwright server beside it, the backend is the container named main, beside searxng and playwright; the commands above would turn them into one. Update each of them instead, with the registry user and a password from Set up a backend in Ada (leave out the containers your backend doesn't have). Unlike the script, these put the password on your command line and in its history:

az webapp sitecontainers update --name "<app>" --resource-group "<resource-group>" --container-name main --image "adavalorconsulting.azurecr.io/ada-backend:<new-version>" `
  --registry-username "<registry-user>" --registry-password "<registry-password>"
az webapp sitecontainers update --name "<app>" --resource-group "<resource-group>" --container-name searxng --image "adavalorconsulting.azurecr.io/ada-searxng:<new-version>" `
  --registry-username "<registry-user>" --registry-password "<registry-password>"
az webapp sitecontainers update --name "<app>" --resource-group "<resource-group>" --container-name playwright --image "adavalorconsulting.azurecr.io/ada-playwright:<new-version>" `
  --registry-username "<registry-user>" --registry-password "<registry-password>"
az webapp restart --name "<app>" --resource-group "<resource-group>"

/api/health reports the running version. The extension and the backend are versioned independently; the extension works with any backend that offers the API version it needs and explains features a backend doesn't offer.

Usage and cost controls

Your organization pays for its own AI usage. Set these as app settings; the defaults apply when a setting is absent:

Setting Default Purpose
LIMIT_REQUESTS_PER_USER_PER_MINUTE 10 Request rate per user
LIMIT_REQUESTS_PER_USER_PER_DAY 200 Requests per user and day
LIMIT_REQUESTS_PER_ORG_PER_DAY 2,000 Requests per organization and day
LIMIT_REQUESTS_GLOBAL_PER_MONTH 50,000 All requests per month
LIMIT_TOKENS_PER_USER_PER_DAY 0 (none) Tokens per user and day, as reported by your provider
LIMIT_TOKENS_PER_ORG_PER_DAY / LIMIT_TOKENS_PER_ORG_PER_MONTH 0 (none) Tokens per organization
MAX_CONCURRENT_REQUESTS / MAX_CONCURRENT_REQUESTS_PER_ORG 10 / 4 Concurrent requests
AI_PROVIDER_MAX_OUTPUT_TOKENS unset Output tokens per request
AI_DISABLED false Emergency switch: refuses all AI requests

Counters are kept in memory: run one instance (don't scale the App Service plan out), or each instance counts separately. Logs contain metadata only (operation, organization, pseudonymous user, duration, outcome, token counts), never prompts, content or credentials.

Optional: pull-request documentation checks

Ada can review completed pull requests on its own and propose Wiki updates for approval (USER-GUIDE.md). The backend then needs storage for proposals and read access to Azure DevOps.

  1. Storage (no account keys; the app identity gets access to one container):

    az storage account create --name "<storage>" --resource-group "<resource-group>" --location "<location>" --sku Standard_LRS --min-tls-version TLS1_2 --allow-shared-key-access false --allow-blob-public-access false
    $st = az storage account show --name "<storage>" --resource-group "<resource-group>" --query id -o tsv
    az role assignment create --role "Storage Blob Data Contributor" --assignee-object-id $me --assignee-principal-type User --scope $st
    az storage container create --account-name "<storage>" --name "ada-state" --auth-mode login
    az role assignment create --role "Storage Blob Data Contributor" --assignee-object-id $principal --assignee-principal-type ServicePrincipal --scope "$st/blobServices/default/containers/ada-state"
    
  2. Hook secret: Set-AdaSecret "pr-docs-hook-secret" with 32+ random characters (generated as in step 3).

  3. Settings:

    az webapp config appsettings set --name "<app>" --resource-group "<resource-group>" --output none --settings `
      "PR_DOCS_ENABLED=true" `
      "PR_DOCS_HOOK_SECRET=@Microsoft.KeyVault(SecretUri=$kv/pr-docs-hook-secret/)" `
      "ADO_AUTH_MODE=managed-identity" `
      "STATE_STORE=blob" `
      "STATE_BLOB_CONTAINER_URL=https://<storage>.blob.core.windows.net/ada-state"
    
  4. Azure DevOps access for the backend: in Organization settings > Users, add the App Service's managed identity ($principal) with Basic access. Grant it Read on the repositories and Wikis to check, and Contribute to pull requests on those repositories (for the reviewer notification). Nothing else.

  5. Who may change the checks: add the app role Ada.Admin to the app registration from step 1 and assign it to those people.

  6. Choose repositories and reviewers in Ada: Ada settings > Admin settings > Pull-request documentation checks.

  7. Service hook, in each project: Project settings > Service hooks > + > Web Hooks, event Pull request updated, URL https://<app>.azurewebsites.net/api/hooks/pull-request, HTTP header x-ada-hook-secret:<the pr-docs-hook-secret value>, resource details All.

Optional: MCP server for AI clients

Coding tools that support the Model Context Protocol (Claude Code, VS Code, Cursor and others) can use Ada's tools at https://<app>.azurewebsites.net/mcp: search over your code, Wikis and work items, a work item with its context, the services a repository is connected to, and more. Each developer's tool sends their own Azure DevOps token, so Azure DevOps is read with their own permissions and no app registration is needed. Anything that would change content becomes a proposal they approve in Ada. What the tools return goes to the AI the developer's coding tool uses.

  1. Set MCP_ENABLED=true, plus STATE_STORE and STATE_BLOB_CONTAINER_URL as for pull-request checks.
  2. Developers open Ada in Your Coding Tool on Ada's Code tab. It shows the file or the command for their tool, with your backend's address filled in.

With the Microsoft sign-in (AUTH_MODE=entra), or when you set MCP_SIGN_IN=entra, the tools sign in with Entra ID instead. On the app registration, under Expose an API, set the Application ID URI (api://<client-id>) and add the delegated scope Ada.Mcp; in the manifest set "accessTokenAcceptedVersion": 2. In the client, use the URL and the header x-azdo-organization: <organization>.

The deployment form (Web Search) and the setup script (-WebSearch) set this up for you: SearXNG runs in a second container and gets only its own secret, not the backend's settings and keys. To add it to a backend that runs without it, run the form or the script again with it (see running the form again, under the quick start), or follow the steps below.

Questions can search the web when the Wiki doesn't answer them, or when the user asks for it (backend 0.11.2 or later). The backend uses SearXNG, a free, self-hosted metasearch engine that passes the question to public search engines (for example Bing, DuckDuckGo, Brave and Wikipedia). It runs as a second container, a sidecar, in the backend's App Service: only the backend reaches it, at http://localhost:8888, and it needs no other Azure resources. The ada-searxng image is SearXNG with the settings the backend needs; use the backend's version.

  1. Secret: Set-AdaSecret "searxng-secret" with 32+ random characters (generated as in step 3).

  2. Sidecar mode: an app with a single container takes sidecars once it's converted. The backend becomes the container named main, with its image and port unchanged:

    az webapp sitecontainers convert --mode sitecontainers --name "<app>" --resource-group "<resource-group>"
    az webapp sitecontainers update --name "<app>" --resource-group "<resource-group>" --container-name main --image "adavalorconsulting.azurecr.io/ada-backend:<version>" `
      --registry-username "<registry-user>" --registry-password "<registry-password>"
    
  3. The SearXNG container:

    az webapp sitecontainers create --name "<app>" --resource-group "<resource-group>" `
      --container-name searxng --image "adavalorconsulting.azurecr.io/ada-searxng:<version>" --target-port 8888 `
      --registry-username "<registry-user>" --registry-password "<registry-password>"
    
  4. Settings. App settings reach every container, so SearXNG reads its secret from here:

    az webapp config appsettings set --name "<app>" --resource-group "<resource-group>" --output none --settings `
      "WEB_SEARCH_PROVIDER=searxng" `
      "WEB_SEARCH_BASE_URL=http://localhost:8888" `
      "SEARXNG_SECRET=@Microsoft.KeyVault(SecretUri=$kv/searxng-secret/)"
    az webapp restart --name "<app>" --resource-group "<resource-group>"
    
  5. Check: turn on Web search in Ada's settings and ask "Search the web for …". App Service > Log stream shows Web search completed with the number of results. With statusCategory: network, the SearXNG container isn't running; its log: az webapp sitecontainers log --name "<app>" --resource-group "<resource-group>" --container-name searxng.

Only the question leaves the backend: SearXNG passes it to the search engines without user information, and they see the App Service's outbound address. Search engines may block data-center addresses, Google most often; SearXNG then pauses that engine for a while and answers from the others. SearXNG is open source under the AGPL-3.0 license (source); the ada-searxng image adds only its settings.

Optional: features that read your code or search your content

These stay off until you set them; the deployment form's Read Code, Code With Ada, Ai Search, Grafana Url or Create Grafana and Mockup Browser set them up for you, as does the setup script's -AllFeatures, and Setup in Ada's organization settings shows what is on. All need STATE_STORE=blob and STATE_BLOB_CONTAINER_URL as for pull-request checks. The features marked "own access" also need the backend's own Azure DevOps access (ADO_AUTH_MODE=managed-identity, as for pull-request checks).

Setting Feature Needs
ARCHITECTURE_DOCS_ENABLED=true Generate Project Documentation and Repository Documentation: Check, and with them Debate Architecture and Review a Pull Request once a project's architecture documentation exists. ARCHITECTURE_MAX_UPLOAD_BYTES limits the code sent per generation (25,000,000 characters by default, at most 60,000,000). Sends source code and Wiki content to your AI provider. The extension reads the repositories with each user's own permissions.
REPO_DOCS_ENABLED=true Repository Documentation: reads all of a repository's code and opens a pull request with its documentation set. Own access, with Read, Contribute, Create branch and Contribute to pull requests on the repositories administrators enable.
CODE_AGENT_ENABLED=true Code with Ada: from a task or a work item to a pull request ready for review, after a person approves the plan. Only organization administrators and the teams they allow see it. Own access, with Read, Contribute, Create branch and Contribute to pull requests on the repositories administrators enable, and View builds and Queue builds on the pipelines that validate their pull requests. Claude as the AI provider (AI_PROVIDER=anthropic or anthropic-vertex).
MOCKUP_DESIGNER_ENABLED=true Mockup Designer. Own access. Its agent needs Claude (AI_PROVIDER=anthropic or anthropic-vertex).
MOCKUP_BROWSER=server, MOCKUP_BROWSER_ENDPOINT=wss://… Lets the Mockup Designer open your test environments in a Playwright browser server you run. A browser server of the same Playwright version as the backend.
DELIGHT_CHECK_ENABLED=true Delight Check: every UI page found in the code scored on Product Delight. Sends UI code to your AI provider.
HOW_IT_WORKS_ENABLED=true How It Works Today: the application's screens described from the code. Sends UI and backend code to your AI provider.
AZURE_SEARCH_ENDPOINT=https://… Ask with search and Diagnose a Ticket. Own access, and Azure AI Search with the roles Search Service Contributor and Search Index Data Contributor for the managed identity.
GRAFANA_URL=https://… Logs and traces for Diagnose a Ticket and Ask. The Grafana Viewer role for the managed identity.
Nothing to set Connections: outside systems that offer an MCP server, whose tools Ada may use in Ask Ada and Diagnose a Ticket. Administrators set them up in Ada (ADMIN-CONFIGURATION.md). Ask with search and Claude as the AI provider. For Azure Managed Grafana, the Grafana Viewer role for the managed identity. For a server that takes a secret, SETTINGS_ENCRYPTION_KEY (32 or more random characters, as a Key Vault reference; the deployment form sets it).

Design Requirements, Access and sprint documents at the end of each sprint need STATE_STORE=blob; Access and sprint documents also need the backend's own access. Administrators then set each feature up under Organization settings > Ada AI.

Rotating secrets

  1. Create a new version of the secret in Key Vault (ai-provider-api-key, entra-client-secret, session-signing-key, pr-docs-hook-secret or searxng-secret). The app settings don't change: the references always use the latest version.
  2. Restart the app (az webapp restart ...) to use it immediately; otherwise App Service picks it up within a day.
  3. Check that AI requests work, then revoke the old credential at its source. Rotating session-signing-key signs everyone out; rotating pr-docs-hook-secret needs the new value in each service hook.

Networking

The defaults above give: HTTPS only with TLS 1.2+, Entra sign-in required, CORS limited to Ada's origin, Key Vault readable only by the app identity, and outbound HTTPS from App Service to your AI provider (with web search, also from SearXNG to the public search engines).

Where required, add App Service VNet integration (with all outbound traffic routed through the VNet) for a private AI endpoint or Key Vault, a Key Vault private endpoint with the privatelink.vaultcore.azure.net DNS zone, and access restrictions on the backend. Behind a proxy, set HTTPS_PROXY and NODE_USE_ENV_PROXY=1.

Troubleshooting

Symptom Check
The app doesn't start; the log stream names a setting Fill that setting. Placeholders such as <app> are rejected.
unresolved Key Vault reference The secret exists, the app identity has Key Vault Secrets User, the vault name in the reference is right, and the network can reach the vault.
/api/ready fails The AI provider settings are incomplete.
Test connection in Ada fails with "could not be reached" The URL starts with https:// and has nothing after the host; ALLOWED_ORIGINS is exactly as in step 4.
Users are asked for admin approval when signing in Step 1.5: grant admin consent.
"The AI provider could not be reached" Outbound access to the provider, the URL, or a proxy (see Networking).
The container doesn't start, and the log shows unauthorized or an image pull failure The registry user or password is wrong or no longer valid. Ask for new credentials at contact@valor-co.com, then set them with az webapp config container set --container-registry-user … --container-registry-password … (with web search, az webapp sitecontainers update --container-name main --registry-username … --registry-password …).
Web search failed with status: 403 in the log The SearXNG container must use the ada-searxng image: plain SearXNG refuses the backend's JSON requests.
AI requests fail with HTTP 400 for newer Claude models Leave AI_PROVIDER_TEMPERATURE empty: Claude 4.7 and later reject it.