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”

Run the first-time installer for your platform.

Terminal window
curl -fsSL https://github.com/githubnext/ado-aw/releases/latest/download/install-linux.sh | sh
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

    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

    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 register the pipeline

    Once you’re happy with the generated files, commit and push them to your Azure DevOps repository. Then register the pipeline with Azure DevOps:

    Terminal window
    ado-aw enable

    This auto-discovers compiled pipelines in your repository and creates (or enables) corresponding ADO build definitions. With the --also-set-token flag, it can also set the GITHUB_TOKEN variable in one step:

    Terminal window
    ado-aw enable --also-set-token

    Alternatively, set the token separately on existing definitions:

    Terminal window
    ado-aw secrets set GITHUB_TOKEN

    Both commands prompt for:

    • The GitHub Personal Access Token (PAT) value — used by the Copilot CLI at runtime (see required permissions below)
    • For Azure DevOps authentication, the commands first try the Azure CLI (az login session). If the Azure CLI is not available or not logged in, they fall back to prompting for an Azure DevOps PAT.

    Service connections for ADO access: If your agent uses safe outputs that write to Azure DevOps (creating PRs, work items, comments, etc.), you need an ARM service connection referenced in your agent file’s permissions.write field. This connection is used to mint short-lived ADO tokens for the executor stage.

    permissions:
      write: my-write-connection  # ARM service connection name

    See Service Connections for step-by-step creation instructions. You can use an existing connection if one is already configured in your project.

  4. Run the pipeline

    Queue your pipeline from the command line:

    Terminal window
    ado-aw run

    Or queue it manually from the Azure DevOps UI. The pipeline executes the three-stage workflow: Agent → Detection → SafeOutputs.

Manual

Section titled “Manual”

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

  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
    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

    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 and register the pipeline

    • Commit both agent.md and the compiled .lock.yml file
    • Push them to your Azure DevOps repository
    • Register the pipeline with Azure DevOps:
    Terminal window
    ado-aw enable

    This auto-discovers the compiled pipeline and creates a corresponding ADO build definition. You can also register and set the GitHub token in one step:

    Terminal window
    ado-aw enable --also-set-token

  4. Set the GitHub token (if not done in step 3)

    If you didn’t use --also-set-token in the previous step, set the token now:

    Terminal window
    ado-aw secrets set GITHUB_TOKEN

    This stores the GITHUB_TOKEN pipeline variable (as a secret) on every matched ADO build definition. See the With Agents section above for details on what the command prompts for and the current GitHub PAT limitation.

    If your workflow uses write-requiring safe outputs, you’ll also need an ARM service connection — see Service Connections.

  5. Run the pipeline

    Back in Azure DevOps, queue your pipeline:

    Terminal window
    ado-aw run

    Or queue it manually from the Azure DevOps UI. The pipeline executes the compiled three-stage workflow: Agent → Detection → SafeOutputs.

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 secrets set GITHUB_TOKEN). It is never exposed to the agent — only the pipeline runtime uses it.

Next steps

Section titled “Next steps”