ado-aw

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`