What GitHub Copilot Reads From Your Azure Boards Items

A developer on your team opens a bug in Azure Boards, clicks the GitHub icon, picks Create a pull request with GitHub Copilot, and fifteen minutes later there is a draft pull request waiting in GitHub. It is linked to the work item, the Kanban card shows a Copilot icon, and everyone is impressed. Then someone opens the diff. The agent fixed the wrong thing, because the real context lived in a linked item, an attachment and a conversation nobody wrote down.

That is the part the setup guides skip. With the Copilot coding agent, the work item is the prompt. Whatever is vague, missing or misplaced in that item becomes a vague, wrong or bloated pull request that a human has to review.

In this post I walk through the setup you actually need, exactly what Copilot receives from an Azure Boards work item (and what it never sees), the kinds of items that fail, and how to put an agent-ready Definition of Ready in front of the agent so your reviewers stop cleaning up after it.

Why the work item is now the prompt

From ticket to draft PR in one click

The Azure Boards integration with GitHub Copilot became generally available in December 2025. From a work item you choose a GitHub repository and branch, optionally add extra instructions, and select Create. The Copilot coding agent then creates a branch, writes the changes and opens a draft pull request that is linked back to the work item. Since February 2026 you can also pick a custom agent at that point.

Nobody opens an IDE first. Nobody asks a clarifying question. The agent starts from the text in the item and nothing else.

Why vague items now cost review time, not just planning time

A human developer picking up a one-line story walks over to the product owner, or at least reads the linked items. That pause used to absorb a lot of bad backlog hygiene. An agent does not pause. It produces something plausible, and plausible is expensive: the reviewer now has to work out what the item meant and whether the code does it.

I made the broader case for this in Guard AI Development at the Work Item, Not the PR. This post is the hands-on version for the Copilot integration specifically.

Setup in 15 minutes: what you actually need

The Microsoft Learn page on using GitHub Copilot with Azure Boards lists the prerequisites. Here is what they mean in practice.

GitHub repos only (Azure Repos isn't supported)

The integration works with GitHub repositories only. If your code lives in Azure Repos, the option creates nothing useful for you. This is one of the reasons many teams keep Boards and move code to GitHub, which I covered in Azure Repos to GitHub: Keep Boards, Links and Your DoD.

The Azure Boards GitHub app and permissions to approve

The connection must use GitHub App authentication. Personal access tokens are not supported. A GitHub organization owner or app manager installs the Azure Boards app from the GitHub Marketplace and selects the repositories it can access. If the app was already installed for the older Boards integration, open the installed GitHub Apps settings, choose Review request on the Azure Boards app and accept the new permissions. If you have not connected Boards to GitHub before, start with Connect Azure Boards to GitHub.

On the Azure DevOps side, the person starting Copilot needs Contribute access to the work item and permission to link artifacts.

Copilot licences and turning on the coding agent

Anyone starting the agent needs a paid GitHub Copilot plan, and the coding agent must be enabled on each target repository. On Copilot Business and Enterprise it is off by default, so an administrator has to turn it on through policy. The GitHub documentation on enabling the Copilot coding agent covers the switches.

Supported work item types

The option appears on work item types in the Requirements and Task categories: User Story, Product Backlog Item, Requirement, Task, Bug and Issue, plus custom types mapped to those categories. If your custom "Change Request" type sits in another category, the button will not be there.

What Copilot receives, and what it never sees

This is the section I wish every guide started with. I build extensions that read and write Azure DevOps work item fields for a living, so the first thing I looked for was the exact input contract.

Title, large text fields, comments and the work item link

According to Microsoft's documentation, Copilot receives:

• the title
• the large text fields, such as Description, Acceptance Criteria and Repro Steps
• the comments (GitHub's documentation specifies the last 50)
• a link back to the work item
• any extra instructions you type in the dialog when you start it

That is the whole list. Microsoft describes it as the only data Copilot receives.

The blind spots

Everything outside that list should be treated as invisible to the agent:

• Linked and parent items. The docs state plainly that Copilot does not handle dependencies between work items. The feature context in the parent, the related bug, the predecessor story: none of it travels.
• Attachments and screenshots. "See the attached mockup" points at nothing.
• Short fields. Tags, Area Path, Priority, Story Points and your custom picklists are not large text fields.
• Tribal knowledge. Decisions made in a refinement session that never reached the description simply do not exist.

The practical rule: if it matters for the code, it must be written in the title, a large text field or a comment.

Your comments end up in the pull request, so scrub them first

There is a governance side to this. Work item content, including comments, is stored in the pull request and visible to anyone with access to the repository. In many organizations the Boards audience and the repository audience are not the same group. Customer names, internal URLs, incident details or a frustrated remark about a supplier can move from a restricted project into a widely shared repo. Make "comments reviewed for sharing" an explicit check, not an afterthought.

Five work items that fail (and how to rewrite them)

These are the patterns I would stop at the door.

The one-liner bug

"Login broken on Safari." No steps, no expected result, no environment. Rewrite it with numbered Repro Steps, the expected versus actual behavior, and the affected browser version. Repro Steps is a large text field, so it reaches the agent.

The story that depends on another story

"Show the discount on the invoice" while the discount calculation is a separate open story. Copilot does not see the dependency. Either finish the dependency first, or state in the description what already exists and what must be stubbed. Keep each item self-contained.

The epic in disguise

A story with eight acceptance criteria touching three services. The agent will try, and the reviewer will receive a huge diff. Split it into child items that each produce a small, reviewable pull request. The usual logic of keeping pull requests small applies, just one step earlier.

The "see attached" item

The design is in a PNG and the API contract in a PDF. Move the parts that matter into the description: the field names, the validation rules, the endpoint shape. Link the design for humans, but write the essentials as text.

The over-explained item

The opposite failure. Microsoft notes that overly complex or verbose descriptions reduce effectiveness. A description that mixes history, debate and three abandoned approaches gives the agent too many candidate instructions. Keep the description to intent, constraints and acceptance criteria, and move the history to comments or remove it.

An agent-ready Definition of Ready

Advice like "write clear descriptions" does not survive a busy sprint. What works is a short Definition of Ready that is based only on what the agent can actually read, and that is enforced before anyone can hand the item to Copilot.

Six checks built only on fields the agent reads

1. Outcome-focused title that names the behavior change, not the component.
2. Description states intent and constraints in a few short paragraphs, including what already exists.
3. Testable acceptance criteria in the Acceptance Criteria field, one observable result per line.
4. No hidden dependencies: blocking items are done, or the description says what to assume.
5. Essentials from attachments copied into text.
6. Comments reviewed for anything that should not appear in the repository.

Notice what is not on the list: story points, tags and area paths. They matter for planning, not for the agent.

Make it blocking, not advisory

A checklist in a wiki is a suggestion. With the Checklist Extension for Azure DevOps, I add those six checks as a reusable template on User Story and Bug, map checklist completion to a field, and use a state transition rule so an item cannot move into a state like Ready for Agent (or Active) until the checklist is complete. The same pattern I described for Done in Make "Done" Mean Done in Azure DevOps Boards works for readiness, and the checklist history gives you an audit trail of who confirmed what.

Agree as a team that only items in that state get sent to Copilot. The gate does the reminding, so nobody has to police it.

Getting items to that bar fast

The gate tells you an item is not ready. It does not make it ready. That is the work ClearSpecs AI does inside Azure DevOps: it rewrites a rough item into a clear title and description, drafts acceptance criteria, and breaks an oversized story into child items. Its chat panel works over your live work items, so you can ask what is missing before you hand an item to the agent. Custom prompt templates let a lead define once what "agent-ready" means for the team.

From draft PR to Done without losing the trail

Reading the status

The work item shows In Progress while Copilot generates changes, Ready for Review when the draft pull request is waiting, and Error if the run failed (hover for details). The Development section lists the branch and pull request, and the board card carries a Copilot icon. Microsoft gives 5 to 15 minutes as a typical duration. After an error, fix the item or the instructions and use Rerun Copilot from the Development area.

You can't cancel, so the gate goes before the run

Once started, the run cannot be cancelled. It goes to completion and you deal with the result in GitHub by closing the draft pull request. That is the strongest argument for putting the quality gate on the work item: after you select Create, the only control left is review.

Custom agents to encode team standards

Custom agents are Markdown profiles (.agent.md) committed to the repository, typically in .github/agents, or shared across an organization from a .github-private repository. Once merged, they show up in the agent selector next to the repository list. Use them for the things that belong to the codebase, such as test conventions and architecture rules. Keep the work item for what belongs to the change.

Closing the work item against your Definition of Done

Review and merge happen in GitHub. The merge commit links to the work item automatically, and the Copilot status indicators disappear after a successful merge. The item itself does not close because a pull request merged. Move it through your normal Definition of Done: tests, review, documentation, whatever your team agreed. An agent-written change deserves the same bar as any other.

Conclusion

The Copilot integration in Azure Boards is easy to switch on: GitHub repos, the GitHub App, a paid Copilot plan, and the coding agent enabled per repository. The hard part is upstream. The agent reads the title, the large text fields, the comments and a link, and nothing else. It ignores dependencies, cannot be cancelled, and copies your comments into a repository audience you may not have intended.

So treat the work item as the prompt. Write items that are self-contained and testable, keep sensitive material out of the comments, and enforce an agent-ready Definition of Ready before anyone presses Create.

If you want help getting your backlog to that standard, try ClearSpecs AI to turn rough items into agent-ready specs, and install the free Checklist Extension to make readiness a gate instead of a hope.

Frequently asked questions