Skip to content
Colony Docs

Connect Azure DevOps End to End

Azure DevOps is a self-hosted/OSS provider. Colony Cloud repository onboarding is GitHub-only, and external review of human-authored pull requests is currently GitHub-only.

Create the provider identities

Section titled “Create the provider identities”

Use two Azure DevOps users when Colony should approve and merge its own pull requests:

  • Coder identity: reads and writes code, creates branches and pull requests, and updates its own PRs.
  • Operations identity: updates work items, publishes review votes, and completes pull requests.

Create PATs with the least access needed for those operations. The coder must have Code read/write access; Colony’s credential check explicitly tests vso.code_write. The operations identity needs Work Items read/write and pull-request contribution/approval. Service-hook creation and branch-policy administration require additional project permissions; grant those only to the operator performing setup when they are not needed at runtime.

Azure DevOps prevents a PR author from supplying the independent approval required by policy. A second PAT variable is optional for manual-merge deployments but required for fully autonomous approval under that policy.

Generate the initial configuration

Section titled “Generate the initial configuration”

Run the interactive generator and select Azure DevOps:

Terminal window
colony config generate

Or configure the literal provider block:

ado:
  organization: acme
  project: Platform
  repo: payments
  token_env: ADO_CODER_PAT
  ops_token_env: ADO_OPS_PAT
  closed_state: Closed
  active_state: Active
  work_item_type_map:
    default: User Story
    bug: Bug
    epic: Epic
    subtask: Task

Set both PAT variables in the Colony installation environment. closed_state, active_state, and work_item_type_map must match the inherited process and work-item types in your Azure DevOps project.

Validate access and initialize the project

Section titled “Validate access and initialize the project”
  1. Run colony check --stage config and correct missing environment variables or invalid mappings.
  2. Run colony check --stage credentials. A PAT that can read code but cannot write will produce a code-write warning.
  3. Run colony check --stage repository to verify the configured project and repository.
  4. Run colony init. ADO uses tags for pipeline-state projection, so no label objects are created.
  5. Inspect the default-branch policy. When permitted, colony init creates or recognizes a blocking minimum-reviewer policy with author votes excluded.

If policy setup reports forbidden or unsupported, configure the equivalent policy in Azure DevOps and keep the runtime PATs narrower.

Configure work-item intake

Section titled “Configure work-item intake”

Start with tagged intake:

agents:
  sprint_master:
    intake_mode: tagged

Colony projects state and flag markers as Azure DevOps tags. Add the Colony enqueue tag to the first test work item. Verify that the configured work-item type maps to the expected ordinary, bug, epic, or subtask behavior before enabling all-work-item intake.

Provider vocabulary also changes in prompts and links: Colony refers to work items, uses AB#<id> references, and treats Azure Pipelines as the CI surface.

Configure service hooks

Section titled “Configure service hooks”

Add receiver authentication to the ADO block:

ado:
  # provider fields omitted
  webhook_username: colony-webhook
  webhook_password_env: ADO_WEBHOOK_PASSWORD

Then:

  1. Start and expose the self-host webhook receiver over HTTPS.
  2. Create Azure DevOps service-hook subscriptions for the work-item and pull-request changes Colony consumes.
  3. Point them to the public receiver URL and configure the same Basic authentication username and password.
  4. Send a test delivery and inspect receiver and Mayor logs.
  5. Confirm the Mayor’s full-sync polling still discovers missed changes.

Use Troubleshoot Webhooks and Provider Permissions for authentication errors and event-path diagnosis.

Configure review and merge

Section titled “Configure review and merge”

Set deterministic checks and begin with manual merge:

review:
  checks:
    build: dotnet build
    test: dotnet test
  auto_merge_on_approval: false

After the coder and operations identities have completed a real test PR, enable auto_merge_on_approval. The ADO branch policy and identity permissions still decide whether the completion request succeeds.

Separate provider and package-feed credentials

Section titled “Separate provider and package-feed credentials”

The PATs in the ado block authenticate Colony to Repos and work items. A private Azure Artifacts npm or NuGet feed uses the separate mounted /colony/keys/credentials.yaml convention. Give a feed PAT Packaging read access and rotate it independently from the provider PATs.

Complete the first work item

Section titled “Complete the first work item”
  1. Create a small work item with an observable acceptance outcome.
  2. Apply the enqueue tag and confirm a single pipeline row appears.
  3. Verify the Worker clones the ADO repository and pushes a branch.
  4. Confirm Colony creates a pull request linked with AB#<id>.
  5. Review checks and votes, then complete the PR manually for the first run.
  6. Confirm the work item reaches the configured closed state and Colony reaches done.

Current limitations

Section titled “Current limitations”
  • Colony Cloud cannot connect an Azure DevOps repository.
  • External review automation for human-authored PRs is GitHub-only.
  • GitHub-specific Apps, labels, check names, and slash-command examples do not map one-for-one to ADO; use ADO PATs, tags, build policy, and work-item states.
  • Azure DevOps Server may differ from Azure DevOps Services, including policy type identifiers and API support; verify on-premises behavior before relying on automated policy setup.

What next

Section titled “What next”