Skip to content
ado-aw

Quick Start

There are two ways to get started with ado-aw — using a Copilot agent to co-create your first workflow interactively, or writing the agent file manually.

Install ado-aw

Section titled “Install ado-aw”

Download the latest release for your platform from GitHub Releases.

Terminal window
curl -fSL "https://github.com/githubnext/ado-aw/releases/latest/download/ado-aw-linux-x64" \
  -o ado-aw
chmod +x ado-aw
sudo mv ado-aw /usr/local/bin/
Section titled “With Agents (recommended)”

The fastest way to create an agentic pipeline is to let Copilot do the heavy lifting.

1. Initialize your project

Section titled “1. Initialize your project”

In your Azure DevOps repository root, run:

Terminal window
ado-aw init

This creates .github/agents/ado-aw.agent.md — a Copilot dispatcher agent that knows how to create, update, and debug agentic pipelines. It auto-downloads the ado-aw compiler and handles the full lifecycle.

2. Co-create a workflow with Copilot

Section titled “2. Co-create a workflow with Copilot”

Open your project in an editor with Copilot and invoke the agent:

/agent ado-aw

Describe what you want your agentic pipeline to do. For example:

“Create a workflow that runs daily, reads open work items tagged ‘stale’, and adds a reminder comment.”

The agent will walk you through the front-matter configuration, write the agent prompt, and compile the pipeline — all interactively.

3. Push and configure

Section titled “3. Push and configure”

Once you’re happy with the generated files, commit and push them to your Azure DevOps repository. Then create a pipeline in Azure DevOps pointing at the compiled .lock.yml file, and configure it:

Terminal window
ado-aw configure

This sets the GITHUB_TOKEN pipeline variable on the ADO build definition. The command prompts for:

  • A GitHub Personal Access Token (PAT) — used by the Copilot CLI at runtime (see required permissions below)
  • For Azure DevOps authentication, the command first tries the Azure CLI (az login session). If the Azure CLI is not available or not logged in, it falls back to prompting for an Azure DevOps PAT.

Run the pipeline in Azure DevOps — it executes the three-stage workflow: Agent -> Detection -> Execution.

Manual

Section titled “Manual”

If you prefer full control, you can author agent files by hand.

1. Create an agent file

Section titled “1. Create an agent file”

Create a file named agent.md:

---
name: Hello from ado-aw
description: A minimal agentic pipeline example
engine:
  id: copilot
on:
  workflow_dispatch:
pool: AZS-1ES-L-MMS-ubuntu-22.04
---


## Instructions


Inspect the repository and summarize what this project does.

This file combines YAML front matter for configuration with markdown instructions for the agent.

2. Compile it

Section titled “2. Compile it”
Terminal window
ado-aw compile agent.md

This writes a compiled .lock.yml pipeline alongside the source file. You should now have:

  • agent.md — your source definition
  • agent.lock.yml — the compiled Azure DevOps pipeline

3. Push to Azure DevOps

Section titled “3. Push to Azure DevOps”
  1. Commit both agent.md and the compiled .lock.yml file.
  2. Push them to your Azure DevOps repository.
  3. In Azure DevOps, create a pipeline that points at the compiled YAML file.
  4. Save the pipeline.

4. Configure the pipeline

Section titled “4. Configure the pipeline”
Terminal window
ado-aw configure

This sets the GITHUB_TOKEN pipeline variable. See the With Agents section above for details on what the command prompts for and the current GitHub PAT limitation.

5. Run the pipeline

Section titled “5. Run the pipeline”

Back in Azure DevOps, run the pipeline. It executes the compiled three-stage workflow: Agent -> Detection -> Execution.

GitHub PAT permissions

Section titled “GitHub PAT permissions”

The Copilot CLI engine requires a fine-grained GitHub Personal Access Token to authenticate. Create one here with the following settings:

SettingValue
Resource ownerYour personal user account (not an organization)
PermissionsAccount permissions -> Copilot Requests: Read

No repository permissions are needed — the token is only used for Copilot inference.

The token is stored as the GITHUB_TOKEN pipeline variable on your Azure DevOps build definition (set by ado-aw configure). It is never exposed to the agent — only the pipeline runtime uses it.

Next steps

Section titled “Next steps”