Get Started: ADOm8 OSS Self-Hosting

Follow these steps to deploy the open-source stack in your own Azure environment. This page is for self-hosted OSS onboarding; managed SaaS customers can skip infrastructure and start directly in-app.

Open-source + free to self-hostEstimated time: 35-50 minAudience: DevOps / Engineering leadsMode: Demo-first, production hardening after validation

✦ Try the step-by-step guideInteractive checklist · one step at a time · track your progress

1. Prerequisites

5 min

Install required tools, clone the repo, and confirm Azure and ADO access before you begin.

View detailed actions

Install Azure CLI (latest) — run 'az login' to verify.
Install .NET 8 SDK — run 'dotnet --version' to verify (must show 8.x).
Install Azure Functions Core Tools v4 — run 'func --version' to verify (must show 4.x).
Install Terraform ≥ 1.0 — run 'terraform --version' to verify.
Install Git — run 'git --version' to verify.
Clone the repo: git clone https://github.com/toddpick/adom8.git
Confirm Azure subscription access with 'Contributor' rights on the target resource group.
Confirm your Azure DevOps organization and project exist and you are a Project Administrator.
Obtain one AI provider API key — Anthropic (Claude), OpenAI, or Azure OpenAI all work.

Commands / Snippets

git clone https://github.com/toddpick/adom8.git

az login

dotnet --version   # expect 8.x

func --version     # expect 4.x

terraform --version

Prerequisites checklist and tool validation commands

2. Create Tokens

5 min

Generate Azure DevOps and GitHub Personal Access Tokens with only the scopes the pipeline needs.

View detailed actions

Azure DevOps PAT — go to your ADO profile → Personal access tokens → + New Token.
Set name: 'AI Agent Bot', expiration: 90 days, scopes: Custom defined.
ADO PAT required scopes: Work Items (Read & Write), Code (Read & Write), Pull Request Threads (Read & Write), Service Hooks (Read, query & manage).
ADO PAT optional scopes (Autonomy Level 5 only): Build (Read & Execute), Pipeline Resources (Use and manage).
GitHub PAT — use a Fine-grained token scoped to your target repo only (most secure).
GitHub PAT required permissions: Contents (Read/Write), Pull requests (Read/Write), Issues (Read/Write), Metadata (Read — auto-granted).
Copy both tokens immediately after creation — you will not be able to see them again.
Store in a password manager; never paste into ADO tickets, screenshots, or .env files committed to source control.

Azure DevOps PAT scope selections and GitHub fine-grained token permissions

3. Configure ADO Process

10-15 min

Create an inherited process, add required workflow states, and add the 22 AI custom fields. Or use PROVISION ADO in the dashboard to automate most of this.

View detailed actions

SHORTCUT: After deploying (Step 4), click 'PROVISION ADO' in the OSS dashboard — it auto-creates states, fields, and the service hook. You can still follow the manual steps below to verify or supplement.
Step 3a — Create an inherited process: Organization Settings → Boards → Process → find your current process (usually Agile/Scrum) → ⋯ menu → 'Create inherited process' → name it 'Agile - AI Agents' → Create.
Step 3b — Switch your project: Organization Settings → Process → click 'Agile - AI Agents' → Projects tab → 'Change team projects to use Agile - AI Agents' → select your project → OK.
Step 3c — Add required User Story states: Process → User Story → States tab → + New state for each: 'AI Agent' (In Progress, blue), 'Code Review' (In Progress, green), 'Needs Revision' (In Progress, red), 'Agent Failed' (In Progress, dark red), 'Ready for QA' (Resolved, green).
State names are CASE-SENSITIVE — 'AI Agent' must match exactly or the webhook trigger will not fire.
Step 3d — Add AI Agent Settings fields: Process → User Story → Layout → + New field: 'Autonomy Level' (Picklist: 1 - Plan Only, 2 - Code Only, 3 - Review & Pause, 4 - Auto-Merge, 5 - Full Autonomy; default: 3 - Review & Pause), group: 'AI Agent Settings'.
Add second field: 'AI Minimum Review Score' (Integer, default: 85), group: 'AI Agent Settings'.
Step 3e — Add AI Tracking field 'Current AI Agent' (Picklist: Planning Agent, Coding Agent, Testing Agent, Review Agent, Documentation Agent, Deployment Agent; default: blank), group: 'AI Tracking'.
Optional: Add remaining 19 AI Tracking fields (AI Tokens Used, AI Cost, AI Review Score, etc.) — pipeline works without them but won't display values on work items.
Step 3f — Board cards: Boards → ⚙️ Team settings → Cards → add 'Current AI Agent' to card fields, then add card style rules per agent value for color-coded ownership.

Commands / Snippets

# Auto-provision via dashboard after Step 4:

# Click PROVISION ADO in the Codebase Intelligence panel

# Or via REST API:

curl -X POST "https://<function-app>.azurewebsites.net/api/provision-ado?code=<FUNCTION_KEY>"

ADO Process settings showing inherited process creation, AI Agent state, and Current AI Agent field

4. Deploy Infrastructure

5-10 min

Use the bootstrap script or Terraform to create the Function App, Storage Account, Application Insights, and Static Web App.

View detailed actions

Fast path — run bootstrap: copy scripts/bootstrap.config.example.json to scripts/bootstrap.config.json, fill in your values, then run the bootstrap script.
Bootstrap creates all Azure resources, sets all app settings, deploys Functions code, and deploys the OSS dashboard in one run.
Manual path — edit infrastructure/terraform.tfvars (copy from terraform.tfvars.example), then run terraform init + apply.
Terraform outputs the Function App name, dashboard URL, and deployment tokens — save these, you'll need them in the next steps.
If using VS Enterprise / MSDN subscription, make sure 'Microsoft.Web' resource provider is registered: az provider register --namespace Microsoft.Web
Bootstrap also supports Key Vault: set keyVault.enabled=true in bootstrap.config.json to automatically wire managed identity + Key Vault secret references.

Commands / Snippets

# Fast path (recommended):

.\scripts\bootstrap.ps1 -InitConfig

# Edit scripts\bootstrap.config.json with your values, then:

.\scripts\bootstrap.ps1 -ConfigPath .\scripts\bootstrap.config.json

# Manual path:

cd infrastructure

cp terraform.tfvars.example terraform.tfvars

terraform init && terraform apply

Bootstrap and Terraform deployment commands with output values

5. Configure Function App

5 min

Set required app settings for AI provider, ADO connection, and repository integration. Bootstrap does most of this automatically.

View detailed actions

If you used bootstrap, most settings are already configured. Use this step to verify or add settings manually.
Go to Azure Portal → your Function App → Configuration → Application settings.
Required AI settings: AI__Provider (anthropic | openai | azureopenai), AI__Model (e.g. claude-sonnet-4-20250514), AI__ApiKey (your provider API key).
Required ADO settings: AzureDevOps__OrganizationUrl (https://dev.azure.com/yourorg), AzureDevOps__Project (your project name), AzureDevOps__Pat (your ADO PAT from Step 2).
Required Git settings: Git__Provider (github | azuredevops), Git__Token (your GitHub PAT from Step 2), Git__Owner (org or user), Git__Repo (repository name).
Optional GitHub Copilot: Copilot__Enabled (true), Copilot__Model (gpt-4o or codex), GitHub__Owner, GitHub__Repo, GitHub__Token.
For production: use Key Vault references (@Microsoft.KeyVault(SecretUri=...)) for all secret values instead of plain text.

Commands / Snippets

# Verify current settings:

az functionapp config appsettings list --name <function-app-name> --resource-group <rg-name>

# Set a value:

az functionapp config appsettings set --name <function-app-name> --resource-group <rg-name> --settings AI__Provider=anthropic

Function App configuration showing required AI, ADO, and Git app settings

6. Configure Service Hook

3 min

Create an ADO Service Hook that fires when a work item moves to 'AI Agent' state, pointing to your Function App.

View detailed actions

In ADO, go to Project Settings → Service hooks → + Create subscription.
Select 'Web Hooks' as the service type → Next.
Trigger: 'Work item updated' event type.
Filter: 'State changes to' = 'AI Agent' (scoping by state prevents firing on every work item edit).
URL: https://<your-function-app>.azurewebsites.net/api/webhook?code=<FUNCTION_KEY>
Get your FUNCTION_KEY from Azure Portal → Function App → Functions → webhook → Function Keys → default.
Optional but recommended: set a shared secret header value and keep it consistent with your WebhookSharedSecret app setting.
Click Test to verify a 200 response, then Finish.

Commands / Snippets

https://<function-app>.azurewebsites.net/api/webhook?code=<FUNCTION_KEY>

ADO Service Hook configuration: Work item updated trigger, AI Agent state filter, webhook URL with function key

7. Launch OSS Dashboard

2 min

Open the free open-source dashboard to monitor pipeline status, queue depth, agent activity, and live logs.

View detailed actions

Your dashboard URL is in the Terraform outputs as 'dashboard_url' or in bootstrap output as 'Static Web App URL'.
You can also find it in Azure Portal → Static Web Apps → your app → URL.
Confirm System Health shows green indicators for ADO, Queue, AI, and Config connections.
In the 'Codebase Intelligence' panel, click PROVISION ADO to auto-create missing ADO states, fields, and service hook from Step 3 (requires Function App to be running with ADO settings configured).
Keep the dashboard open during first tests — it shows live agent progress, queue depth, token usage, and cost per story.

Commands / Snippets

# Get dashboard URL from Terraform outputs:

cd infrastructure && terraform output dashboard_url

OSS dashboard showing System Health, Agent Pipeline, queue activity, and live agent status

8. Verify End-to-End

5 min

Move a test story to 'AI Agent' state and watch the pipeline execute — queue picks up, agents run sequentially, PR is created.

View detailed actions

Create a simple User Story with a clear title, description, and acceptance criteria (the agents use these to generate code).
Set 'Autonomy Level' to '1 - Plan Only' for a safe first test — it will plan but not write or push any code.
Move the work item state to 'AI Agent'.
Within ~10 seconds the webhook fires and the story appears in the dashboard queue.
Watch 'Current AI Agent' update on the work item as each agent completes.
Check Application Insights for detailed telemetry: portal.azure.com → your app insights → Live Metrics.
After success with Level 1, try Level 3 (Review & Pause) — agents run fully and create a PR, then pause for your code review.
Confirm the branch and pull request were created on GitHub.

Commands / Snippets

# Check Function App health:

curl https://<function-app>.azurewebsites.net/api/status?code=<FUNCTION_KEY>

# Stream live logs:

az functionapp log stream --name <function-app-name> --resource-group <rg-name>

Dashboard showing active pipeline with agent stepper, queue depth, and story progression

9. Production Hardening

10-20 min

Apply least-privilege and perimeter controls before sharing your instance with a wider team or exposing it publicly.

View detailed actions

Secrets — move all API keys and PATs into Azure Key Vault. Grant only 'Key Vault Secrets User' to the Function App's managed identity. Use @Microsoft.KeyVault(...) references in app settings.
CORS — in Function App → CORS settings, remove the wildcard (*) and add only your dashboard hostname.
Dashboard access — configure Azure Static Web App authentication (Entra ID or ADO) to restrict who can open the dashboard.
Network — optionally enable access restrictions on the Function App to allow only ADO webhook IPs and your dashboard origin.
Alerts — set an Azure Monitor alert on the poison queue (queue name: agent-jobs-poison) so you know immediately when agents fail repeatedly.
Rotate — set a calendar reminder to rotate PATs before their expiration date (recommend 90-day expiry + 14-day reminder).
See SECURITY_HARDENING.md in the repo for the complete hardening checklist with copy-paste commands.

Production hardening checklist: Key Vault secret references, CORS lock-down, SWA auth, and poison queue alert

Self-Host OSS

You control infrastructure, credentials, networking, and access policies in your Azure environment.

Step-by-step guide See How It Works Open OSS Setup Security Hardening