azure-devops

Original：🇺🇸 English
Translated

Complete Azure DevOps automation - boards, repos, pipelines, artifacts

4installs
Sourcerysweet/amplihack
Added on

NPX Install

npx skill4agent add rysweet/amplihack azure-devops

Tags

Translated version includes tags in frontmatter
azure-devops-automationwork-items-managementpipeline-automationartifact-managementrepo-operations

SKILL.md Content

View Translation Comparison →

Azure DevOps Skill

Complete Azure DevOps integration covering boards, repositories, pipelines, and artifacts.
Auto-activates when: User mentions Azure DevOps, ADO, work items, boards, repos, pipelines, artifacts, or Azure DevOps URLs.

Purpose

This skill provides comprehensive guidance for Azure DevOps automation through purpose-built Python CLI tools that handle:

Work Items (Boards)

  • Work item creation with HTML-formatted descriptions
  • Work item updates (state, assignments, fields)
  • Work item deletion with confirmation
  • Parent-child relationship linking
  • WIQL query execution
  • Work item type and field discovery

Repositories

  • Repository listing with details
  • Pull request creation with reviewers and work items
  • Branch validation
  • Clone URL access

Pipelines

  • Pipeline listing and execution
  • Build monitoring and logs
  • Deployment management

Artifacts

  • Package feed management
  • Package publishing and downloading
  • Version management

Quick Start

1. Authentication First

ALWAYS start by checking authentication:
bash
python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix
This verifies Azure CLI is installed, you're logged in, org/project are configured, and you have access.
See: [@authentication.md]

2. Common Operations

Create Work Item

bash
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "Implement feature" \
  --description @story.md

Query Work Items

bash
python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

Create Pull Request

bash
python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/branch \
  --target main \
  --title "Add feature"

Progressive Loading References

For detailed guidance on specific operations, see:
  • [@authentication.md] - Authentication methods (PAT, OAuth, environment variables)
  • [@work-items.md] - Work item CRUD operations, field updates, state transitions
  • [@queries.md] - WIQL query patterns, filtering, sorting
  • [@html-formatting.md] - HTML formatting in work item descriptions/comments
  • [@repos.md] - Repository operations, pull request workflows
  • [@pipelines.md] - Pipeline triggers, build monitoring, deployment
  • [@artifacts.md] - Package management, artifact publishing
  • [@HOW_TO_CREATE_YOUR_OWN.md] - Template for creating similar integration tools

Available Tools

ToolPurposeWhen to Use
auth_check.py
Verify authenticationBefore any operations
create_work_item.py
Create work itemsAdd User Stories, Tasks, Bugs, etc.
update_work_item.py
Update work itemsChange state, assignee, fields
delete_work_item.py
Delete work itemsRemove work items (with confirmation)
get_work_item.py
Get work item detailsView complete work item info
list_work_items.py
Query work itemsFind, filter, and list work items
link_parent.py
Link parent-childCreate Epic → Feature → Story hierarchies
query_wiql.py
Execute WIQL queriesComplex filtering with WIQL
format_html.py
Convert to HTMLFormat rich descriptions
list_types.py
Discover types/fieldsExplore available options
list_repos.py
List repositoriesView all repositories in project
create_pr.py
Create pull requestSubmit code for review

Common Patterns

Pattern 1: Create Work Item with Parent

bash
# Create parent work item
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Epic" \
  --title "Q1 Planning Initiative" \
  --description @epic_desc.md

# Output: Created work item #12345

# Create child and link to parent
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Feature" \
  --title "Authentication System" \
  --description @feature_desc.md \
  --parent-id 12345

# Output: Created work item #12346 and linked to parent #12345

Pattern 2: Query and Update Work Items

bash
# Find your active work items
python .claude/scenarios/az-devops-tools/list_work_items.py \
  --query mine \
  --format ids-only

# Update work item state
python .claude/scenarios/az-devops-tools/update_work_item.py \
  --id 12345 \
  --state "Active" \
  --comment "Starting work on this"

Pattern 3: Feature Branch to Pull Request

bash
# List repositories
python .claude/scenarios/az-devops-tools/list_repos.py

# Create pull request
python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/auth \
  --target main \
  --title "Add authentication" \
  --description @pr_desc.md \
  --reviewers "user1@domain.com,user2@domain.com" \
  --work-items "12345,12346"

Pattern 4: Discover Available Types

bash
# List all work item types in your project
python .claude/scenarios/az-devops-tools/list_types.py

# Show fields for specific type
python .claude/scenarios/az-devops-tools/list_types.py \
  --type "User Story" \
  --fields

Critical Learnings

HTML Formatting Required

Azure DevOps work item descriptions use HTML, not Markdown or plain text.
The tools handle this automatically:
  • create_work_item.py
    converts markdown to HTML by default
  • Use 
    --no-html
    to disable conversion
  • Or use 
    format_html.py
    directly for custom formatting
See: [@html-formatting.md]

Two-Step Parent Linking

You cannot specify a parent during work item creation via CLI (Azure limitation).
The tools provide two approaches:
Option A: Use 
--parent-id
flag (recommended):
bash
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Task" \
  --title "My Task" \
  --parent-id 12345
Option B: Link separately:
bash
# Step 1: Create
TASK_ID=$(python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "Task" \
  --title "My Task" \
  --json | jq -r '.id')

# Step 2: Link
python .claude/scenarios/az-devops-tools/link_parent.py \
  --child $TASK_ID \
  --parent 12345

Area Path and Work Item Types

  • Area path format: 
    ProjectName\TeamName\SubArea
  • Work item types vary by project (standard + custom types)
  • Use 
    list_types.py
    to discover what's available in your project

Error Recovery

ErrorTool to UseExample
Authentication failed
auth_check.py --auto-fix
Auto-login and configure
Invalid work item type
list_types.py
See available types
Field validation error
list_types.py --type "Type" --fields
See valid fields
Parent link failedCheck IDs exist, verify hierarchy rulesEpic → Feature → Story → Task
Branch does not existVerify with 
git branch -a
Push branch first

Tool Implementation

All tools are in 
~/.amplihack/.claude/scenarios/az-devops-tools/
:
  • Standalone Python programs (can run independently)
  • Importable modules (can use in other scripts)
  • Comprehensive error handling
  • Tests in 
    tests/
    directory
See: Tool README

Philosophy

These tools follow amplihack principles:
  • Ruthless Simplicity: Each tool does one thing well
  • Zero-BS: Every function works, no stubs or TODOs
  • Reusable: Importable and composable
  • Fail-Fast: Clear errors with actionable guidance
  • Self-Contained: Standard library + azure CLI wrapper only

Quick Reference

bash
# Setup (first time)
python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

# Create work item
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "Title" \
  --description @desc.md

# Update work item
python .claude/scenarios/az-devops-tools/update_work_item.py \
  --id 12345 \
  --state "Active"

# Query work items
python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

# Create pull request
python .claude/scenarios/az-devops-tools/create_pr.py \
  --source feature/branch \
  --target main \
  --title "Add feature"

# Discover types
python .claude/scenarios/az-devops-tools/list_types.py