Archigov · docs
  1. Docs
  2. Guides

Connect Azure DevOps

Feed epics and features into Archigov as planned changes — by WIQL backfill and a service hook — to flag missing decisions and requirements that changed after approval.

#A Feed, Not a Gate

Azure DevOps is a source of planned change, not a workflow Archigov controls. Archigov reads epics and features and tells you two things:

  • Needs a decision — an open Epic, Project, Initiative or Change that is linked to no architecture decision and no review.
  • Changed after approval — a linked work item whose requirements changed materially after its design was approved.

Nothing in Azure DevOps is blocked or written to. These items appear under Planned Changes, on the Overview pipeline, and in authors' work queues.

The Planned Changes page
Planned Changes: epics and features from the feed, with the ones that need a decision or changed after approval flagged.

#1. Credentials

Either:

  • a personal access token with Work Items (Read), in ADO_PAT; or
  • an Entra identity (the same AZURE_* service principal or managed identity) added to the Azure DevOps organisation with read access. Without ADO_PAT, Archigov requests a token for https://app.vssps.visualstudio.com/.default.

Tip

Prefer the Entra identity. It avoids long-lived tokens, and it keeps working as organisations restrict global PATs.

#2. Configure

Env
ADO_ORG=<organisation>
ADO_PROJECT=<project>
ADO_PAT=<token>                 # or rely on the Entra identity
ADO_HOOK_SECRET=<random string> # required for the service hook
ADO_WIQL=                       # optional; see below

The default backfill query reads epics and features that are not removed and changed in the last year:

SQL
SELECT [System.Id] FROM WorkItems
WHERE [System.WorkItemType] IN ('Epic','Feature') AND [System.State] <> 'Removed'
  AND [System.ChangedDate] >= @Today - 365
ORDER BY [System.ChangedDate] DESC

#3. Backfill

As the platform admin, Settings → Sources → Azure DevOps: Test, then Sync. The backfill runs the WIQL query and fetches items in batches.

#4. Service Hook

For changes as they happen, create a service hook subscription in Azure DevOps (Project settings → Service hooks → Web Hooks):

SettingValue
EventsWork item created, Work item updated, Work item deleted, Work item restored
URLhttps://archigov.example.org/api/hooks/ado
HTTP headersx-archigov-hook-secret: <ADO_HOOK_SECRET>
Basic authenticationAlternatively, put the secret in the password field

Calls without the correct secret receive 401. The hook endpoint is exempt from sign-in because it carries its own secret.

What happens when a work item changesLanes: Azure DevOps, Archigov, Author. Steps: Work item created or changed (Azure DevOps); Service hook → /api/hooks/ado (Azure DevOps); Secret valid? (Archigov); 401 (Azure DevOps); Upsert the planned change (Archigov); Needs a decision? (Archigov); Draft a decision from the item (Author); Changed after approval? (Archigov); Acknowledge, or take it back to the board (Author); Recorded (Archigov). Transitions: Work item created or changed to Service hook → /api/hooks/ado; Service hook → /api/hooks/ado to Secret valid?; Secret valid? to 401 (no); Secret valid? to Upsert the planned change (yes); Upsert the planned change to Needs a decision?; Needs a decision? to Draft a decision from the item (yes); Needs a decision? to Changed after approval? (no); Changed after approval? to Acknowledge, or take it back to the board (yes); Changed after approval? to Recorded (no).Azure DevOpsArchigovAuthorWork item created orchangedService hook →/api/hooks/adoor the WIQL backfillSecret valid?401Upsert the plannedchangeNeeds adecision?Draft a decision fromthe itemChanged afterapproval?Acknowledge, or takeit back to the boardRecordednoyesyesnoyesno
What happens when a work item changes

#Working with Planned Changes

  • Link a work item to an application or a review.
  • Draft Decision from a work item: a template, or an AI draft if Decision Drafting is enabled. The author edits and submits.
  • Acknowledge a material change once the board has considered it.
  • Log by hand: authors can record planned changes no backlog knows yet (PC-0001). Items from a real source are read-only in Archigov; manual ones can be set to Removed rather than deleted.