Connect @devintern/pm to Azure DevOps work items

Azure DevOps Integration

@devintern/pm creates Azure DevOps work items directly from AI-generated stories and tasks. Setup takes a few minutes — you need a Personal Access Token, your organization slug, and a target project.

How It Works

@devintern/pm uses the Azure DevOps Work Items REST API to create items in a project you configure.

• New work items appear in the target project with the issue type you select (User Story, Bug, Task, etc.)
• Descriptions are converted from markdown to HTML for System.Description (Azure DevOps defaults to HTML; raw markdown would display as plain text)
• Subtasks are created as Task work items linked as children of the parent
• Epic links use Azure DevOps parent/child hierarchy relationships
• Work item IDs are numeric (e.g. 123) — use the ID from the work item URL when linking epics

This integration targets Azure DevOps Services (dev.azure.com). Self-hosted Azure DevOps Server is not supported.

Setup

1. Set the backend

In your .devintern-pm/.env:

TASK_TRACKER=azure-devops
AZURE_DEVOPS_ORG=your-organization
AZURE_DEVOPS_PAT=your-pat-token
AZURE_DEVOPS_PROJECT=YourProject

All three Azure DevOps variables are required.

2. Find your organization slug

Open your organization in the browser. The slug is the segment after dev.azure.com/:

https://dev.azure.com/contoso/MyProject/_workitems/edit/123
                    └─ org ─┘

Set AZURE_DEVOPS_ORG=contoso — the slug only, not the full URL.

3. Create a Personal Access Token

1. Go to Personal Access Tokens (replace your-org with your organization slug)
2. Click + New Token
3. Set a name (e.g. DevIntern) and choose an expiration
4. Under Scopes, enable:
   • Work Items: Read & write
   • Project and Team: Read
5. Under Organizations, select your org (or All accessible organizations if you use multiple)
6. Create the token and copy it into AZURE_DEVOPS_PAT

Store the PAT in .devintern-pm/.env — that file should stay out of version control (devpm init adds it to .gitignore).

4. Set your default project

AZURE_DEVOPS_PROJECT must match the project name exactly as shown in Azure DevOps — not the project ID or description.

Find it in the URL when you open a board or backlog:

https://dev.azure.com/contoso/MyProject/_boards/board/t/...
                              └─ project name ─┘

Or copy the name from Project settings → Overview.

In interactive mode you can switch projects with Ctrl+P before confirming, but AZURE_DEVOPS_PROJECT is still required as the default.

5. Create your first work item

devpm --interactive

The issue type step lists work item types from your project’s process template (Agile, Scrum, Basic, CMMI, or a custom process).

Issue Types

Available types depend on your Azure DevOps process template:

@devintern/pm fetches the types configured in your project. Pick a type that exists in your process — if you choose a type that is not defined, work item creation will fail.

What Gets Created

When linking to an epic, enter the parent work item’s numeric ID (from the URL: .../_workitems/edit/456 → 456), not a Jira-style key like PROJ-123.

Troubleshooting

“Azure DevOps backend selected but … configuration is missing”

Set all three variables in .devintern-pm/.env: AZURE_DEVOPS_ORG, AZURE_DEVOPS_PAT, and AZURE_DEVOPS_PROJECT.

“Azure DevOps API error (401)”

• PAT is invalid or expired — create a new token
• Confirm the token was copied without extra spaces
• Verify the token’s organization scope includes the org in AZURE_DEVOPS_ORG

“Azure DevOps API error (403)”

• PAT lacks Work Items (Read & write) scope — regenerate with the correct permissions
• Your account may not have permission to create work items in the target project — ask a project admin to grant Contributors access or equivalent

“Azure DevOps API error (404)” when creating work items

• AZURE_DEVOPS_ORG or AZURE_DEVOPS_PROJECT is wrong — check the slug and project name against your Azure DevOps URL
• Project name is case-sensitive and must match exactly (including spaces)

Work item creation fails with an invalid work item type

• The selected type does not exist in your process template (e.g. choosing Story on a Scrum project that uses Product Backlog Item)
• Re-run interactively and pick a type from the list, or use --type with a valid type name for your project

Descriptions show raw markdown syntax (e.g. ##, **bold**)

Azure DevOps System.Description defaults to HTML via the REST API. @devintern/pm converts markdown to HTML before creating the work item. If you still see unrendered markdown on older work items, those were likely created before this conversion was added.

Azure DevOps also supports an opt-in Markdown format (/multilineFieldsFormat/System.Description = Markdown) on organizations with the New Boards markdown editor — @devintern/pm uses HTML for compatibility with the default format.

Subtask creation fails

• Subtasks are always created as Task work items. If your process template does not include Task (unusual), subtask creation will fail
• Confirm the parent key is a numeric work item ID that exists in the project

Epic link fails with “Work item not found”

• Azure DevOps uses numeric IDs, not Jira-style keys — enter the epic’s work item ID (e.g. 456 from .../_workitems/edit/456)
• Both the story and epic must exist in a project your PAT can access

Project picker (Ctrl+P) shows other projects but defaults elsewhere

Work items are created in the project selected in interactive mode, or in AZURE_DEVOPS_PROJECT when not overridden. Ensure the default project name matches the project you intend to use.