Connect Azure DevOps
For organisation admins. Connects your Speclr organisation to Azure DevOps once through Microsoft Entra ID, so project teams can use Azure Repos, Azure Boards and the project wiki.
Updated
Use a dedicated machine account
- Clear authorshipEvery pull request, work item and wiki page Speclr writes appears under the account you connect.
- Survives people leavingA personal account takes all hand-overs down with it when its owner leaves.
- Own request budgetAzure DevOps limits requests per user. A machine account keeps Speclr's status reads apart from anyone's own work.
One Azure DevOps connection serves three things: Azure Repos as the repository, Azure Boards as the ticket system and a project wiki for the requirements documentation. Each project team picks what it uses. Speclr works with Azure DevOps Services at dev.azure.com; Azure DevOps Server cannot be connected.
Create the account in Microsoft Entra ID
Speclr signs in through Microsoft Entra ID, so the account must be a work or school account in your organisation's tenant, such as
speclr-bot@acme.com. Personal Microsoft accounts, such as outlook.com addresses, cannot connect.- Multi-factor authentication on, sign-in details stored with the team
- Allowed to sign in to Speclr by your Conditional Access policies
Add the account to your Azure DevOps organisation
In Azure DevOps, open Organization settings › Users › Add users and add the account. If your organisation is connected to your Entra tenant, adding it is enough; nobody has to accept an invitation. In each project your teams will use, add it to the project's Contributors group: that lets it write code, edit work items and edit the wiki.
Give it the access level Basic. With Stakeholder, Azure DevOps lets it neither write code nor add new tags, assign iterations or change the backlog order.
- Access level Basic, not Stakeholder
- Member of Contributors in each project
- "Create child nodes" on the project's iterations, so Speclr can create an iteration per milestone
Let Speclr in, if your tenant asks an admin
Many Entra tenants let only admins approve apps from other companies. If Microsoft shows that Speclr needs admin approval, an Entra admin with at least the Cloud Application Administrator role approves it once: Entra ID › Enterprise apps › All applications › Speclr › Permissions › "Grant admin consent". Then connect again.
A Conditional Access policy can also block the sign-in, for example one that allows only managed devices. Your Entra admin can exclude the machine account or allow Speclr.
Connect in Speclr, signed in as the machine account
Open Organisation settings › Integrations › Discover and choose "Connect" on Azure DevOps. Only organisation admins see the integrations. When Microsoft asks you to sign in, use the machine account, not your own. A private browser window avoids mix-ups.
Microsoft then asks you to accept the permissions Speclr requests for Azure DevOps:
offline_access vso.profile vso.project vso.work_write vso.code_manage vso.wiki_write. You only consent; the permissions are set by Speclr.Back in Speclr, the connection appears under Yours and reads "Acts as" the account. Check that it is the machine account. Speclr reaches every Azure DevOps organisation the account is a member of.
Check the permissions
The permissions let Speclr do no more than the account itself may do in each project. Speclr uses them for:
- Code
- read, write to branches, create repositories, open pull requests
- Work items
- create, edit and order; create iterations
- Wiki
- read and write pages
- Projects and teams
- read, to list them in the project settings
- Profile
- read the account's name and organisations
Pick what each Speclr project uses
Any member of a Speclr project can do this, in Project settings › "Integrations".
Repository: the list shows Azure DevOps repositories as
acme/Shop/shop-api: organisation, project and repository, in a group "Azure DevOps" if GitHub or GitLab is connected too. "Create new repository…" creates one in a project you choose. Azure DevOps does not tell in advance whether the account may push, so Speclr finds out the first time it writes.Work items: choose the project under "Azure Boards". Once saved, the row reads "Saved · Features or Epics found". If the project's process has no backlog level above its requirements, the row warns "This project has no backlog level above its requirements, such as Features or Epics. Stories cannot be handed over to it until it has one." There is no "Board" row: see the order below.
Parent page: the row reads "Azure DevOps is connected. Choose a wiki, then a page in it." Choose "Choose page", pick a wiki, then a page; each page shows its path. "Change wiki" goes back to the list. Once saved, the row reads "Saved · the page was found in the Azure DevOps wiki", and Speclr asks "Put the requirements documentation into the Azure DevOps wiki?".
What Speclr creates in Azure Repos
Speclr opens a pull request from a branch speclr/…. It carries AGENTS.md, the docs/ foundation set (with docs/risks.md once your team tracks risks) and a spec and feature file per story. With "Commit directly instead of opening a change request", Speclr commits to the target branch instead; a branch policy that requires pull requests refuses that. Speclr never force-pushes and never overwrites a change it has not seen. An empty repository first gets a commit with a README.
What Speclr creates in Azure Boards
Speclr reads the project's process instead of assuming names. For each story you hand over:
- A work item per activity on the backlog level above the requirements: a Feature, or an Epic in the Basic process. An existing one with exactly the activity's name is reused.
- A work item for the story, of the requirement level's default type (User Story, Product Backlog Item, Requirement or Issue, by process), as a child of its activity. Its title starts with the story id, for example
US-014 · Set a spending limit. Azure DevOps names itAB#12. - A tag for the step. An existing tag is reused regardless of case.
- An iteration for the milestone, found by name below the project's root or created. If the account may not create it, the work item carries a tag instead: "The iteration MVP could not be created. The work item carries the tag MVP instead."
- The backlog order, so the stories appear in Speclr's order of priority.
Iterations Speclr creates are not in a team's sprints until the team selects them under its settings. The work items carry them anyway, so queries and the backlog's Iteration column show them. A sprint your team set on a work item is kept.
The description starts with Speclr's part: an origin line ("Generated by Speclr · edit in Speclr · exported …"), the specification and the scenarios. Everything below it belongs to your team and is never touched.
If someone edits inside Speclr's part, Speclr does not overwrite it. The story shows, for example, "AB#12 was edited in Azure Boards.", and your team decides in Speclr: "Keep the Azure DevOps version" or "Replace with version N". If the part is broken, Speclr writes nothing to that description and the run report says "The Speclr part of the Azure Boards description must be repaired." A work item deleted in Azure DevOps shows "AB#12 no longer exists."
Status and pull requests
Speclr reads the state category of each work item and never changes it. "In Progress" and "Resolved" show as in progress, "Completed" as merged, "Removed" as discarded. Custom states count by their category.
If the Speclr project also has a repository, Speclr links pull requests and branches to the story when the branch name or the pull request title names the work item, such as AB#12. That works with Azure Repos, GitHub and GitLab.
What Speclr creates in the wiki
Below the parent page, Speclr creates the project page, for example Shop – Requirements, with the req42 pages below it, such as 1. Vision and goals. They hold the same content as in Notion; Connect Notion describes each section. The pages are Markdown and start with the origin line as a quote. If the project is renamed, Speclr moves the project page, and the pages below it move along.
Edit the content in Speclr. A page someone edited in the wiki is not overwritten: the "Wiki" row says, for example, "5. Supporting models was edited in the Azure DevOps wiki." "Resolve…" lets your team keep the wiki's version or "Replace with the Speclr version". A page deleted in the wiki shows "… no longer exists."; choose "Recreate the page" or "Detach". Your team's own pages inside the project page are never touched.
Optional: allowed owners
Limit project teams to repositories of chosen Azure DevOps organisations, e.g. acme. An allowed organisation includes all its projects. Repositories outside the list receive nothing.
Limits
- Azure DevOps shows no avatars to Speclr. Who edited a work item or page is named without a picture.
- Pull requests and branches count for a story only when they name its work item, such as AB#12.
- If a page of the same title as one of Speclr's already exists below the parent page, that page fails, and Speclr never writes over it.
Reconnect or disconnect
Reconnect when the connection shows "Nothing is handed over until it is reconnected", as the same machine account. Microsoft also asks for consent again whenever Speclr's permissions change. Another account first names the affected projects.
Disconnecting names them too. Targets and links stay; status turns unknown.
Troubleshooting
- Microsoft does not accept the account: personal Microsoft accounts cannot connect. Use a work or school account of your tenant.
- Microsoft says Speclr needs admin approval, or Conditional Access blocks the sign-in: ask your Entra admin, as described under Admin consent.
- An organisation, project or repository is missing from the lists: the account is not a member of it. Add it as described in step 2, and check the allowed owners.
- "The target branch does not accept direct commits.": a branch policy requires pull requests. Turn direct commits off, or change the policy.
- "The Azure Boards project needs a backlog level above its requirements, such as Features or Epics.": turn on that backlog level in the project's process, or choose another project.
- "Speclr can no longer create work items in Azure Boards · acme/Shop. Ask an Azure DevOps admin for access, or choose another project.": add the account to the project's Contributors group.
- "Speclr can no longer write below Home. Ask an Azure DevOps admin for permission to edit the wiki, or choose another page.": the account needs permission to edit the wiki.
- "A page titled 1. Vision and goals already exists below Shop – Requirements in the Azure DevOps wiki. Rename that page, or choose another parent page.": your team made a page of that name. Rename it in the wiki.
- "An admin must reconnect the Azure DevOps connection.": reconnect as the machine account.
- A pull request does not show at the story: name the work item, such as AB#12, in the branch name or the pull request title.
