Add TestADORoundTripCoreFields, TestADORoundTripBlockedStatus, TestADORoundTripLossyPriority, and TestADORoundTripLabels which verify push→pull fidelity through a stateful mock ADO REST server. Key findings documented in tests: - Core fields (title, priority, status, type) survive round-trip - Blocked status preserves via beads:blocked tag mechanism - Priority 4 (Backlog) is lossy: degrades to P3 after fresh pull - User labels survive; internal beads:* tags filtered on pull Also add docs/ADO_CONFIG.md with comprehensive configuration reference covering connection settings, filter options, default mappings for all three process templates (Agile/Scrum/CMMI), state transition handling, sync options, and troubleshooting guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
327 lines
9.8 KiB
Markdown
327 lines
9.8 KiB
Markdown
# Azure DevOps (ADO) Integration Configuration
|
|
|
|
This guide covers all configuration options for the `bd ado sync` command, which synchronizes beads issues with Azure DevOps work items.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```sql
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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"**
|
|
```bash
|
|
bd config set ado.pat "your-pat-here"
|
|
# or
|
|
export AZURE_DEVOPS_PAT="your-pat-here"
|
|
```
|
|
|
|
**"Azure DevOps organization not configured"**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
```
|