beads/docs/integrations/azure-devops.md
Chris Sells a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.

git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).

Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.

Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2026-07-12 10:37:07 -07:00

9.9 KiB

title
Azure DevOps (ADO) Integration Configuration

Last reviewed: 2026-05-08

Freshness source: cmd/bd/ado*.go and internal/ado/.

This guide covers all configuration options for the bd ado sync command, which synchronizes beads issues with Azure DevOps work items.

Quick Start

# Set required config
bd config set ado.pat "your-personal-access-token"
bd config set ado.org "your-organization"
bd config set ado.project "your-project"

# Or use environment variables
export AZURE_DEVOPS_PAT="your-personal-access-token"
export AZURE_DEVOPS_ORG="your-organization"
export AZURE_DEVOPS_PROJECT="your-project"

# Sync (bidirectional)
bd ado sync

# Pull only (import from ADO)
bd ado sync --pull-only

# Push only (export to ADO)
bd ado sync --push-only

# Preview without making changes
bd ado sync --dry-run

Connection Configuration

Config Key Env Variable Required Description
ado.pat AZURE_DEVOPS_PAT Yes Personal Access Token
ado.org AZURE_DEVOPS_ORG Conditional¹ Organization name (e.g., myorg)
ado.url AZURE_DEVOPS_URL Conditional¹ Custom base URL (on-prem ADO Server)
ado.project AZURE_DEVOPS_PROJECT Conditional² Single project name
ado.projects AZURE_DEVOPS_PROJECTS Conditional² Comma-separated project names

¹ Either ado.org or ado.url must be set. Use ado.url for on-premises Azure DevOps Server.

² At least one project must be configured via ado.project or ado.projects.

Config vs env var precedence: Config keys (set via bd config set) take priority over environment variables.

On-Premises ADO Server

For Azure DevOps Server (on-prem), use ado.url instead of ado.org:

bd config set ado.url "https://tfs.company.com/DefaultCollection"
bd config set ado.project "MyProject"

Multi-Project Sync

Sync across multiple projects in a single command:

bd config set ado.projects "ProjectA,ProjectB,ProjectC"

The first project is used as the primary for URL construction. WIQL queries use TeamProject IN (...) for multi-project support.

Filter Configuration

Filters control which ADO work items are included in sync operations.

Config Key CLI Flag Description Example
ado.filter.area_path --area-path Area path (uses UNDER) Project\Team
ado.filter.iteration_path --iteration-path Sprint/iteration path Project\Sprint 1
ado.filter.types --types Work item types (comma-separated) Bug,Task,User Story
ado.filter.states --states ADO states (comma-separated) New,Active,Resolved

CLI flags override config values for that sync run.

WIQL query example (generated from filters):

SELECT [System.Id] FROM WorkItems WHERE
  [System.TeamProject] = 'MyProject'
  AND [System.IsDeleted] = false
  AND [System.AreaPath] UNDER 'Project\Team'
  AND [System.WorkItemType] IN ('Bug', 'Task')
  AND [System.State] IN ('New', 'Active')
  ORDER BY [System.ChangedDate] ASC

Default Mappings

Priority Mapping

Priority mapping is bidirectional but lossy for P3/P4:

Beads Priority ADO Priority Direction Notes
0 (Critical) 1 ↔
1 (High) 2 ↔
2 (Medium) 3 ↔ Default for unknown values
3 (Low) 4 →
4 (Backlog) 4 → Lossy: becomes P3 on pull

Note: Beads P3 and P4 both map to ADO priority 4. On a fresh pull into an empty database, ADO 4 maps back to beads P3. The original priority is not preserved across a full round-trip for P4 issues.

For Bug-type work items, ADO also requires a Severity field:

Beads Priority ADO Severity
0 1 - Critical
1 2 - High
2 3 - Medium
3, 4 4 - Low

Status Mapping

Beads Status Default ADO State Config Key
open New ado.state_map.open
in_progress Active ado.state_map.in_progress
blocked Active + beads:blocked tag ado.state_map.blocked
deferred Removed ado.state_map.deferred
closed Closed ado.state_map.closed

Blocked status: ADO has no native blocked state. beads maps blocked to Active and adds a beads:blocked tag. On pull, Active + beads:blocked tag restores StatusBlocked.

Override defaults for your process template:

# Example: Scrum template
bd config set ado.state_map.open "To Do"
bd config set ado.state_map.in_progress "In Progress"
bd config set ado.state_map.closed "Done"

Type Mapping

Beads Type Default ADO Type Config Key
bug Bug ado.type_map.bug
feature User Story ado.type_map.feature
task Task ado.type_map.task
epic Epic ado.type_map.epic
chore Task ado.type_map.chore

Reverse mapping (ADO → beads) also recognizes:

  • Product Backlog Item → feature (Scrum template)
  • Issue → task

Override for your process template:

# Example: Scrum template
bd config set ado.type_map.feature "Product Backlog Item"

Process Template Configuration

ADO supports multiple process templates with different work item types and state transitions. The defaults assume the Agile template. Override mappings for other templates.

Agile (Default)

No configuration needed. Default mappings work out of the box.

State transitions:

Bug:         New → Active → Resolved → Closed
Task:        New → Active → Closed
User Story:  New → Active → Resolved → Closed
Epic:        New → Active → Resolved → Closed

Scrum

bd config set ado.type_map.feature "Product Backlog Item"
bd config set ado.state_map.open "New"
bd config set ado.state_map.in_progress "Committed"
bd config set ado.state_map.closed "Done"

State transitions:

Product Backlog Item: New → Approved → Committed → Done
Task:                 To Do → In Progress → Done
Bug:                  New → Approved → Committed → Done

CMMI

bd config set ado.type_map.feature "Requirement"
bd config set ado.state_map.open "Proposed"
bd config set ado.state_map.in_progress "Active"
bd config set ado.state_map.closed "Closed"

State transitions:

Requirement: Proposed → Active → Resolved → Closed
Task:        Proposed → Active → Closed
Bug:         Proposed → Active → Resolved → Closed

State Transition Handling

When creating a work item in a non-initial state (e.g., pushing a closed issue), beads:

  1. Creates the item in the initial state (e.g., New)
  2. Transitions through intermediate states to reach the target
  3. Example: Creating a closed Bug → New → Active → Resolved → Closed

If a direct transition fails (ADO returns 400), beads automatically walks the known transition path for the work item type and process template.

Sync Options

Direction

Flag Description
(none) Bidirectional: pull then push
--pull-only Import from ADO only
--push-only Export to ADO only

Conflict Resolution

When the same issue has been modified both locally and in ADO:

Flag Description
--prefer-newer Most recently updated version wins (default)
--prefer-local Local beads version always wins
--prefer-ado ADO version always wins

Additional Flags

Flag Description
--dry-run Preview sync without making changes
--no-create Only update existing items, never create new ones
--bootstrap-match Enable heuristic title matching for first sync
--reconcile Force reconciliation scan for deleted items
--issues Sync specific issues by bead ID or ADO work item ID
--label Filter by label
--status Filter by beads status
--type Filter by beads issue type

PAT Permissions

The Personal Access Token needs these scopes:

Scope Access Required For
Work Items Read & Write Creating and updating work items

Generate a PAT at: https://dev.azure.com/{org}/_usersettings/tokens

Metadata Preserved

beads stores ADO-specific metadata for round-trip fidelity:

Metadata Key Description
ado.rev ADO revision number
ado.area_path Area path
ado.iteration_path Iteration/sprint path
ado.story_points Story points estimate
ado.remaining_work Remaining work hours
ado.severity Bug severity value

Description Conversion

  • Push (beads → ADO): Markdown converted to HTML
  • Pull (ADO → beads): HTML converted to Markdown

Tags and Labels

  • ADO tags are semicolon-separated; beads labels use arrays
  • User labels round-trip through ADO tags
  • Internal beads:* tags (e.g., beads:blocked) are filtered on pull — they don't appear as user labels

API Limits

Limit Value
Max batch size 200 work items per GET request
Max response size 50 MB
Request timeout 30 seconds
Max retries 3 (GET and WIQL only)
Retry backoff Exponential with jitter, respects Retry-After header

Troubleshooting

Common Errors

"Azure DevOps PAT not configured"

bd config set ado.pat "your-pat-here"
# or
export AZURE_DEVOPS_PAT="your-pat-here"

"Azure DevOps organization not configured"

bd config set ado.org "your-org"
# or for on-prem:
bd config set ado.url "https://tfs.company.com/DefaultCollection"

State transition errors (400 Bad Request) This usually means the process template doesn't support a direct state change. Check your ado.state_map.* config matches your actual process template.

Type not found errors Verify your ado.type_map.* config matches the work item types available in your project. Use --types filter to restrict which types are synced.

Debugging

# Preview what would happen
bd ado sync --dry-run

# Check current config
bd config get ado.pat
bd config get ado.org
bd config get ado.project