Publish a changelog from Azure Boards

Teams that deploy from Azure Boards already have a record of what shipped. The work items are there, the branches are linked, and the pipeline runs are logged. What is usually missing is the step that turns all of that into something a customer can read.

This guide covers a workflow that produces a public changelog as a by-product of deploying, rather than as a separate chore someone remembers at the end of the month.

Why the usual approaches fail

The common fault is sourcing from the wrong thing. A changelog should come from what actually reached customers, which is the deployment record, and the wording should be written by a person after the fact.

The workflow

1. Deploy from the work item. Each deployment records the work item, its title and type, the branch, the environment, and the outcome. This is the source list, and it builds itself.
2. Write up a release when you are ready. Open Release notes in your BranchDeploy account and look at the recent deployments. Decide which ones a customer would notice. Most will not qualify — infrastructure work, refactors and reverts belong in your audit log, not your changelog.
3. Rewrite each item. The work item title is pre-filled as a starting point. Replace it with the benefit, in the customer's language. "Fix #4102 regression in ProfileValidator" becomes "Sign-up now accepts apostrophes in surnames."
4. Categorise honestly. The type is pre-set from the Azure DevOps ticket type, so a Bug becomes a fix. Change it where the ticket type and the customer impact disagree.
5. Publish. Nothing is public until you do. The entry appears on your JSON feed and hosted page at the same moment.

Writing items customers will read

• Lead with the change, not the component. "Checkout is faster" beats "Optimised the checkout service".
• Drop internal nouns. Service names, table names, ticket numbers and branch names mean nothing outside your team.
• Say what someone can now do. If a change has no observable effect, it probably does not belong in the changelog.
• Keep security entries vague. "Hardened session handling" is enough. Do not describe the vulnerability.
• One entry per release, not per deployment. A ticket deployed to test and then production is one change your customers experience once.

Choosing where it is published

You can publish to a read-only JSON feed, a page BranchDeploy hosts, or both from the same entry.

Use the JSON feed if you want the changelog inside your product — a "What's new" panel, a modal after sign-in, or a notification badge. You fetch it from your own front end with no authentication, and render it however you like.

Use the hosted page if you want a link you can send to customers without building anything. Add your logo and brand colour so it looks like yours rather than ours.

Keeping it accurate over time

Two things protect a changelog from drifting out of date. Deployments you have already written up disappear from the candidate list, so you cannot announce the same change twice or lose track of where you got to. And published output is a snapshot: editing a draft never changes what the public sees until you publish again, so a half-finished edit cannot leak.

If you publish something you should not have, archiving withdraws it from the feed and page immediately, and deleting removes it permanently.

Next steps

Release notes are included with BranchDeploy Pro, and a feed is created automatically for each project you sync. See the release notes documentation for the JSON schema and integration examples, or the feature overview for how it fits together.