ado-aw

Azure DevOps Agentic Workflows. Write agentic workflows in human-friendly
markdown; ado-aw compiles each into a secure, multi-stage Azure DevOps pipeline
that runs an AI agent in a network-isolated sandbox.

Inspired by GitHub Agentic Workflows (gh-aw).

If you are an AI agent, use the specialized prompts in prompts/ for step-by-step guidance: create · update · debug

How It Works

You author an agent file — a markdown document with YAML front matter that
describes what the agent should do, when it should run, and which tools it
can use. The ado-aw compiler transforms that file into a production-ready Azure
DevOps pipeline built around three core security stages:

┌────────────────────────┐     ┌──────────────────────┐     ┌───────────────────────┐
│  Agent                 │────▶│  Detection           │────▶│  SafeOutputs          │
│  (Stage 1 — Agent)     │     │  (Stage 2 — Threats) │     │  (Stage 3 — Executor) │
│                        │     │                      │     │                       │
│  • Runs inside AWF     │     │  • Reviews proposed  │     │  • Creates PRs        │
│    network sandbox     │     │    actions for safety│     │  • Creates work items │
│  • Read-only ADO token │     │  • Checks for prompt │     │  • Write ADO token    │
│  • Produces safe       │     │    injection, leaks  │     │  • Never exposed to   │
│    output proposals    │     │                      │     │    the agent          │
└────────────────────────┘     └──────────────────────┘     └───────────────────────┘

The agent never has direct write access. All mutations (pull requests, work items)
go through a safe outputs pipeline where they are threat-analyzed and then
executed with a separate, scoped write token.

Quick Start

1. Install

Run the first-time installer for your platform:

# Linux (x64)
curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-linux.sh | sh

# macOS (Apple Silicon)
curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-macos.sh | sh

# Windows (x64)
$script = Join-Path $env:TEMP "install-ado-aw.ps1"
Invoke-WebRequest "https://github.com/githubnext/ado-aw/releases/latest/download/install-windows.ps1" -UseBasicParsing -OutFile $script
Get-FileHash $script -Algorithm SHA256
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
& $script

The installers download the release binary, verify it against checksums.txt, install it to a standard path (/usr/local/bin when writable, otherwise a user-local path), and update your PATH when needed.

Compare the Get-FileHash output with the install-windows.ps1 entry in checksums.txt before running the script.

If you see The Process object must have the UseShellExecute property set to false in order to use environment variables, run the five Windows commands above from an existing PowerShell prompt (not via a nested powershell -Command ... launch).

2. Initialize Your Repository

ado-aw init

This creates a Copilot agent at .github/agents/ado-aw.agent.md that helps you create, update, and debug agentic workflows. The agent automatically downloads the ado-aw compiler and handles compilation.

3. Create an Agent with AI

Ask your coding agent (Copilot, Claude, Codex) to create a workflow:

Create an ADO agentic workflow using
https://raw.githubusercontent.com/githubnext/ado-aw/main/prompts/create-ado-agentic-workflow.md

The purpose of the workflow is to check for outdated dependencies weekly
and open PRs to update them.

Or if you've run ado-aw init, simply ask your AI agent:

Create an agentic workflow that checks for outdated dependencies and opens PRs

The AI will generate a markdown file like:

---
name: "Dependency Updater"
description: "Checks for outdated dependencies and opens PRs"
engine:
  id: copilot
  model: claude-opus-4.7
on:
  schedule: weekly on monday around 9:00
pool:
  vmImage: ubuntu-22.04
tools:
  azure-devops: true
permissions:
  read: my-read-arm-connection
  write: my-write-arm-connection
safe-outputs:
  create-pull-request:
    target-branch: main
    draft: false
    auto-complete: true
    squash-merge: true
    reviewers:
      - "[email protected]"
---

## Instructions

Check all dependency manifests in this repository. For each outdated
dependency, update it to the latest stable version and create a pull
request with a clear description of what changed and why.

4. Compile to a Pipeline

# Simple form — generates a `.lock.yml` alongside the source `.md`
ado-aw compile dependency-updater.md

# Or specify a custom output location
ado-aw compile dependency-updater.md -o path/to/dependency-updater.lock.yml

This generates a complete Azure DevOps pipeline YAML file. The compiler also
copies the agent markdown body into the output tree so it's available at runtime.

The compiler also writes/updates a .gitattributes file at the repository root
that marks every compiled .lock.yml pipeline as linguist-generated=true merge=ours,
so GitHub hides them from PR diffs and merge conflicts in generated YAML resolve
to the local copy (which can then be rebuilt with ado-aw compile).

5. Verify (CI Check)

Ensure pipelines stay in sync with their source:

ado-aw check dependency-updater.lock.yml

This is useful as a CI gate — if someone edits the markdown but forgets to
recompile, the check will fail.

Adding the Pipeline to Azure DevOps

Step 1: Commit both files

Your repo should contain the agent source .md and the compiled pipeline .lock.yml.
Place them wherever your team's conventions dictate — there is no required directory structure.

Push both files to your Azure DevOps repository.

Step 2: Create the pipeline in Azure DevOps

1. Go to Pipelines → New Pipeline
2. Select your repository
3. Choose Existing Azure Pipelines YAML file
4. Point to the compiled .lock.yml pipeline file
5. Save (or Save & Run)

Step 3: Set Up ARM Service Connections for Permissions

This is the most important configuration step. Azure DevOps does not support
fine-grained PAT scoping — tokens are either read or read-write across the
project. To maintain security isolation between the agent and the executor,
you need two separate ARM service connections:

Why Two Connections?

The agent runs in a network-isolated sandbox (AWF) with only the read token.
Even if the agent were compromised or prompt-injected, it cannot perform write
operations. Write actions are only executed in Stage 3 (SafeOutputs)
after threat analysis, using a completely separate token that the agent never
sees.

Creating the Service Connections

1. Navigate to Project Settings → Service connections → New service connection

2. Choose Azure Resource Manager → Service principal (automatic) (or manual if
   your organization requires it)

3. Create two connections:

   Read connection (e.g., ado-agent-read):

   • Scope: subscription or resource group level
   • Grants: the ability to mint read-only ADO-scoped tokens
   • Used by: the agent job to call az account get-access-token with the
     ADO resource ID (499b84ac-1321-427f-aa17-267ca6975798)

   Write connection (e.g., ado-agent-write):

   • Scope: subscription or resource group level
   • Grants: the ability to mint read-write ADO-scoped tokens
   • Used by: the executor job to create PRs, work items, etc.

4. Reference them in your agent front matter:

   permissions:
     read: ado-agent-read
     write: ado-agent-write

[!NOTE]
permissions.write is optional. The Stage 3 executor always has a
write-capable token available via $(System.AccessToken) (the pipeline's
built-in OAuth token, running as Project Collection Build Service). Configure
permissions.write only when you need cross-org writes or named-identity
attribution — it overrides the default token with an ARM-minted credential.

Permission Combinations

Step 4: Authorize the Pipeline

On the first run, Azure DevOps will prompt you to authorize the pipeline to use
the service connections. Approve the permissions and the pipeline is ready.

Agent File Reference

Front Matter Fields

Markdown Body

Everything below the front matter --- fence is the agent's instructions. Write
natural language describing the task, constraints, and expected behavior.

Trigger Configuration

The on: field configures when an agent pipeline fires. Three trigger types
are supported — mix and match as needed.

on.schedule — recurring schedule

The on.schedule field uses a fuzzy syntax that deterministically scatters
execution times based on the agent name, preventing load spikes.

The expressions below are the value of the schedule: key under on:. For
example:

on:
  schedule: daily around 14:00

# Daily
on:
  schedule: daily                          # Scattered across 24 hours
on:
  schedule: daily around 14:00             # Within ±60 min of 2 PM
on:
  schedule: daily between 9:00 and 17:00   # Business hours

# Weekly
on:
  schedule: weekly on monday around 9:00   # Monday morning

# Multi-day / Special periods
on:
  schedule: every 2 days                   # Every 2 days at scattered time
on:
  schedule: every 2 weeks                  # Every 14 days at scattered time
on:
  schedule: bi-weekly                      # Every 14 days at scattered time
on:
  schedule: tri-weekly                     # Every 21 days at scattered time

# Hourly / Minute intervals
on:
  schedule: hourly                         # Every hour, scattered minute
on:
  schedule: every 2h                       # Every 2 hours (valid: 1, 2, 3, 4, 6, 8, 12)
on:
  schedule: every 15 minutes               # Fixed, not scattered

# With timezone
on:
  schedule: daily around 14:00 utc+9       # 2 PM JST → 5 AM UTC

# With branch filtering
on:
  schedule:
    run: daily around 14:00
    branches:
      - main
      - release/*

on.pr — pull request trigger

Triggers the pipeline on pull request activity. Two independent filter layers are available:

Use native ADO filters for broad exclusions; use filters: for runtime context
(PR title, author, labels, changed files, etc.).

# Minimal — trigger on any PR
on:
  pr: {}

# Scoped to specific branches and changed files
on:
  pr:
    branches:
      include: [main, release/*]    # only PRs targeting these branches
    filters:
      changed-files:
        include: ["src/**", "*.ts"] # only when these paths are touched
      draft: false                  # skip draft PRs

# Gate on a label (agent runs only when "run-agent" label is present)
on:
  pr:
    filters:
      labels:
        any-of: ["run-agent"]

mode controls how PR builds reach the pipeline:

on:
  pr:
    mode: policy   # requires a Build Validation branch policy to be configured in ADO

ADO Azure Repos note. ADO ignores the YAML pr: block unless a Build
Validation branch policy is installed. mode: synthetic (the default)
works around this by detecting open PRs via the ADO API on every push —
the agent runs on PR branches and self-skips on non-PR branches.
See front-matter reference for on.pr details and all filters: options.

on.pipeline — upstream pipeline completion

Triggers the pipeline when another ADO pipeline finishes.

on:
  pipeline:
    name: "CI Build"               # source pipeline name (required)
    project: "OtherProject"        # only when in a different ADO project
    branches: [main, release/*]    # omit to trigger on any branch

# With runtime filters
on:
  pipeline:
    name: "CI Build"
    filters:
      branch: "refs/heads/main"    # only builds on main
      time-window:
        start: "09:00"             # only during business hours (UTC)
        end:   "17:00"

When on.pipeline (or on.schedule) is set, CI push and PR triggers are
suppressed (trigger: none, pr: none). Add on.pr: explicitly to keep
PR triggers active alongside a schedule or pipeline trigger.

MCP Servers

MCP (Model Context Protocol) servers give the agent access to external tools.

Built-in Tools (via tools:)

First-class integrations are configured under the tools: front matter field —
not under mcp-servers:. The compiler auto-generates all required pipeline steps
and network allowlist entries.

tools:
  # Bash command allow-list. Omit or use [":*"] for unrestricted access;
  # set to [] to disable bash entirely. See docs/tools.md.
  bash: ["git status", "git diff", "npm test"]

  # File editing tool (read/write/patch files in the workspace). Default: true.
  edit: true

  # Azure DevOps MCP — query work items, repos, PRs, etc.
  azure-devops: true

  # With scoping options
  azure-devops:
    toolsets: [repos, wit]
    allowed: [wit_get_work_item, repo_list_repos_by_project]
    org: myorg               # Optional — inferred from git remote by default

  # Persistent memory across agent runs
  cache-memory: true

  # With options
  cache-memory:
    allowed-extensions: [.md, .json]

Tip: Enabling cache-memory auto-injects a clearMemory boolean
parameter into the pipeline, so anyone queuing a run manually in the ADO UI
can wipe the agent's persisted memory before it starts. See
docs/parameters.md for the full runtime-parameters
reference.

Custom MCP Servers (via mcp-servers:)

For external or third-party MCPs, use the mcp-servers: field. Each entry is
either a containerized stdio server (Docker-based) or an HTTP server
(remote endpoint). All traffic routes through the MCP Gateway (MCPG).

mcp-servers:
  # Docker container stdio MCP
  my-tool:
    container: "node:20-slim"
    entrypoint: "node"
    entrypoint-args: ["path/to/mcp-server.js"]
    # enabled: set to false to temporarily disable without removing the entry
    # args: additional Docker runtime arguments inserted before the image name
    #   (e.g. ["--memory", "512m"]).  Dangerous flags like --privileged trigger
    #   a compile-time warning.
    args: []
    # mounts: volume mounts in "source:dest:mode" format
    mounts:
      - "/host/data:/app/data:ro"
    # env: environment variables for the MCP container process.
    #   Use "" (empty string) as the value to forward the variable from the
    #   pipeline environment (passthrough); supply a literal string for static
    #   values.
    env:
      MY_SECRET: ""          # passthrough from pipeline env
      STATIC_VALUE: "hello"  # literal value
    allowed:
      - search
      - analyze

  # Remote HTTP MCP
  remote-api:
    url: "https://mcp.example.com/api"
    headers:
      X-MCP-Toolsets: "repos,wit"
    allowed:
      - wit_get_work_item

Custom MCP containers run inside the AWF network sandbox. Add any required
external domains to network.allowed.

Safe Outputs

Safe outputs are the only way agents produce side effects. The agent proposes
actions, and the executor processes them after threat analysis.

Example: Pull Request Configuration

safe-outputs:
  create-pull-request:
    target-branch: main
    draft: false             # PRs are drafts by default; set false to publish immediately (required for auto-complete)
    auto-complete: true
    delete-source-branch: true
    squash-merge: true
    max-files: 50             # Reject the PR if it touches more files than this (default: 100)
    protected-files: blocked  # "blocked" (default) rejects edits to manifest/CI files; "allowed" permits them
    excluded-files:
      - "**/*.generated.ts"
    reviewers:
      - "[email protected]"
    labels:
      - automated
    work-items:
      - 12345

max-files and protected-files are safety limits, not cosmetic knobs — they
reject an agent-authored PR outright if it touches too many files or edits a
protected manifest/CI path (e.g. package-lock.json, .github/, *.lock).
See docs/safe-outputs.md for the full field list,
including target-branches, infer-target-from-checkout-ref, title-prefix,
if-no-changes, allowed-labels, fallback-record-branch, and
include-stats.

Example: Work Item Configuration

safe-outputs:
  create-work-item:
    work-item-type: Bug
    area-path: "MyProject\\MyTeam"
    assignee: "[email protected]"
    tags:
      - agent-created
      - needs-triage

Threat Detection (threat-detection)

The Detection stage's AI analysis pass is on by default and needs no configuration. To tune or disable it, use the reserved threat-detection key under safe-outputs::

safe-outputs:
  threat-detection:
    enabled: true            # false skips the AI analysis call (Detection job still runs)
    prompt: "Treat any change to pricing constants as a malicious patch."
    engine:
      model: gpt-4.1          # override the Agent's model for Detection only

See the site reference for the full field list, including steps/post-steps for raw ADO steps around the analysis.

Manual Review (require-approval)

High-impact safe outputs can be gated behind a human approval step. When the agent proposes a gated action, the pipeline inserts a ManualValidation step between Detection and SafeOutputs. A reviewer must approve before the output is applied.

Set require-approval: true per tool, or use the detailed form for approvers and timeout:

safe-outputs:
  create-pull-request:
    target-branch: main
    require-approval: true          # Gate this tool behind manual review
  create-work-item:
    work-item-type: Task
    require-approval:
      approvers: ["my-ado-group"]        # Optional: who can approve (empty = anyone with run access)
      notify-users: ["[email protected]"] # Optional: who receives a notification email
      timeout-minutes: 1440              # Optional: 24h; default = ADO job/stage limit
      on-timeout: reject                 # "reject" (fail-closed, default) or "resume" (auto-approve)
      instructions: "Review carefully before approving."

See docs/safe-outputs.md for the full reference.

Network Isolation

Agents run inside AWF (Agentic Workflow Firewall)
containers with L7 domain allowlisting. Only explicitly allowed domains are
reachable. The allowlist is built from:

1. Core domains — Azure DevOps, GitHub, Microsoft auth, Azure storage
2. MCP domains — automatically added per enabled MCP
3. User domains — from network.allowed in front matter
4. Minus blocked — network.blocked entries are removed from the
   combined allowlist. Both ecosystem identifiers (e.g. python) and raw
   domain strings are supported. Blocking an ecosystem identifier removes
   all of its domains; blocking a raw domain uses exact-string matching
   (blocking "github.com" does not also remove "*.github.com").

network:
  allowed:
    - "*.mycompany.com"
    - "api.external-service.com"
  blocked:
    - "analytics.tracking.com"

CLI Reference

• audit <build-id-or-url> - Audit a single Azure DevOps build: download artifacts, analyze logs, render Markdown or JSON report. See docs/audit.md.

ado-aw [OPTIONS] <COMMAND>

Commands:
  init          Initialize a repository for AI-first agentic workflow authoring
  compile       Compile markdown to pipeline definition
  check         Verify a compiled pipeline matches its source
  mcp           Run as an MCP server (safe outputs)
  mcp-author    Run the author-facing MCP server over stdio (IDE/Copilot Chat integration)
  execute       Execute safe outputs (Stage 3)
  secrets       Manage pipeline-variable secrets on matched ADO definitions (set/list/delete)
  enable        Register ADO build definitions for compiled pipelines and ensure they are enabled
  disable       Set queueStatus to disabled (or paused) on matched ADO definitions
  remove        Delete matched ADO build definitions (destructive)
  list          List matched ADO definitions with their latest-run state
  status        Per-pipeline status block for matched ADO definitions
  run           Queue builds for matched ADO definitions (optionally poll to completion)
  audit         Audit a single Azure DevOps build: download artifacts, analyze logs, render a report
  trace         Trace a build's failing-job chain using audit data plus the local IR graph
  inspect       Inspect an agent source file's typed IR: jobs, stages, steps, outputs, derived `dependsOn`
  graph         Query the resolved dependency graph for an agent source file
  whatif        Static reachability: classify jobs skipped if a step or job fails
  lint          Run structural lint checks over an agent source file
  catalog       List safe-outputs, runtimes, tools, engines, models, and versions

Options:
  -v, --verbose              Enable info-level logging
  -d, --debug                Enable debug-level logging
      --log-output-dir <path>  Write ado-aw logs to a specific directory (overrides ADO_AW_LOG_DIR)

Note: The configure command is deprecated (hidden from --help) and is now just an alias for secrets set GITHUB_TOKEN. Use secrets set GITHUB_TOKEN directly.

The secrets command has three subcommands:

• ado-aw secrets set <name> [value] — set a pipeline variable (isSecret=true) on every matched definition. Value may be passed positionally, via --value-stdin, or prompted interactively.
• ado-aw secrets list — list variable names and flags on every matched definition. Never prints values.
• ado-aw secrets delete <name> — delete a pipeline variable from every matched definition.

All three accept --all-repos / --source <path> for project-scope (Preview-driven) discovery instead of local-fixture matching. See docs/cli.md for the full flag reference.

Prompts & Skill Files

ado-aw provides specialized prompt files that guide AI agents through common tasks. Use these with any coding agent (Copilot, Claude, Codex, etc.):

Using Prompts with Your AI Agent

Paste the raw URL into your coding agent's chat:

Create an ADO agentic workflow using
https://raw.githubusercontent.com/githubnext/ado-aw/main/prompts/create-ado-agentic-workflow.md

The purpose of the workflow is to <describe what you want>

The AI agent will fetch the prompt, follow its instructions, and create a complete workflow file for you.

Documentation

The docs/ directory contains per-concept reference pages. Use this
index to jump to the right page.

Authoring agent files

• docs/front-matter.md — full agent file format
  (markdown body + YAML front matter grammar) with every supported field.
• docs/engine.md — engine: configuration (model,
  timeout-minutes, version, agent, api-target, args, env,
  provider, command, github-app-token).
• docs/tools.md — tools: configuration (bash allow-list,
  edit, cache-memory, azure-devops MCP).
• docs/runtimes.md — runtimes: configuration (Lean 4,
  Python, Node.js, .NET).
• docs/runtime-imports.md — runtime prompt-import
  markers, path resolution, and inlined-imports: behavior.
• docs/schedule-syntax.md — fuzzy schedule time
  syntax with timezones and scattering.
• docs/parameters.md — ADO runtime parameters surfaced
  in the pipeline UI.
• docs/conclusion.md — Conclusion job — the
  always-running post-pipeline housekeeping job (triggered by safe-outputs:)
  that files work-item reports for failures and diagnostic signals.
• docs/targets.md — target platforms: standalone, 1es,
  job, and stage.
• docs/execution-context.md — built-in
  aw-context/ precompute contributors for PR, manual, pipeline, CI/push,
  work-item, scheduled, PR-check, and repository context.
• docs/safe-outputs.md — full reference for every
  safe-output tool plus their per-agent configuration.
• docs/safe-output-permissions.md —
  diagnosis and fix reference for Stage 3 permission failures (401/403).
• docs/supply-chain.md — optional supply-chain:
  front-matter section for internal feed/registry mirrors and exact
  provenance-checked pipeline artifacts.
• docs/ado-aw-debug.md — debug-only ado-aw-debug:
  front-matter section (skip-integrity, create-issue).

Compiler internals & operations

• docs/prompt-evals.md — deterministic prompt
  contracts and a gh-aw-managed static base-versus-head review against
  synthetic scenarios and scoring rubrics.
• docs/ir.md — typed Azure DevOps pipeline IR (Pipeline,
  jobs/stages/steps, output refs, graph pass, lowering, and target builders).
• docs/cli.md — ado-aw CLI command and flag reference.
• docs/agency-plugin.md — the Agency / Claude Code
  plugin (agency/plugins/ado-aw/): canonical layout, six skills, mcp-author
  wiring, the self-contained root marketplace catalogs, init --agency
  scaffolding, release-please version-locking, and shared-marketplace listing.
• docs/audit.md — ado-aw audit: accepted build-id / URL
  forms, artifact layout, cache behavior, rejection tracing, and AuditData
  report shape.
• docs/mcp.md — MCP server configuration (stdio containers,
  HTTP servers, env passthrough).
• docs/mcp-author.md — author-facing MCP server
  reference for local IDE/Copilot Chat integrations.
• docs/mcpg.md — MCP Gateway architecture and pipeline
  integration.
• docs/network.md — AWF network isolation, default
  allowed domains, ecosystem identifiers, blocking, and ADO permissions:
  service-connection model.
• docs/filter-ir.md — filter expression IR for PR
  trigger filters and gate-step generation.
• docs/codemods.md — front-matter codemod framework
  (detection-based source rewrites on breaking-change updates).
• docs/ado-script.md — scripts/ado-script/ workspace
  (bundled TypeScript runtime helpers: gate.js, import.js, and the
  execution-context exec-context-*.js bundles).
• docs/extending.md — adding new CLI commands, compile
  targets, front-matter fields, typed IR extensions, safe-output tools,
  first-class tools, and runtimes.
• docs/local-development.md — local development
  setup notes.

Development

# Build
cargo build

# Test
cargo test

# Lint
cargo clippy

This project uses Conventional Commits
for automated releases via release-please.

License

See LICENSE for details.