Azure DevOps

Hamstik for Azure DevOps connects source-control and delivery evidence from an Azure DevOps Services organization to Hamstik Projects. Azure DevOps remains the source of truth for repositories, pull requests, builds, pipelines, environments, and releases. Hamstik remains the ALM and Work Item system.

Preview acceptance status

The Application is implemented and locally validated. Acceptance against the live Microsoft and blackboardstudios Azure DevOps contracts remains required before general availability.

Azure Boards is not connected

Hamstik does not read or synchronize Azure Boards, backlogs, iterations, epics, stories, bugs, or tasks. The Application does not request an Azure Boards permission and does not write Hamstik Work Items to Azure DevOps.

Supported capabilities

For explicitly selected Azure DevOps Projects, Hamstik reads:

Azure Repos Git repositories, default branches, refs, recent commits and pushes;
pull requests, lifecycle state, completion or abandonment, current reviewers, and reviewer votes;
Build definitions and Build runs, including repository, branch, commit, reason, state, result, timing, timeline jobs, and artifact metadata;
Pipeline definitions and Pipeline runs, including declared repository resources;
modern Azure Pipelines environments and deployment history;
Classic Release definitions, releases, release environments, Build artifacts, and deployment attempts; and
links between repository, commit, pull request, build or run, deployment, and environment when Azure DevOps supplies sufficient evidence.

Build and Pipelines are related Azure DevOps API surfaces, but Hamstik preserves their different identifiers and resource models. It does not invent a relationship when provider evidence is missing. Logs, artifact files, approvals/checks, and non-Build Classic artifact correlation are not copied.

Prerequisites

Before connecting:

an Organization owner or administrator must be able to manage Hamstik Apps;
the Microsoft identity used for authorization must be able to access the intended Azure DevOps Services organization and Projects;
a platform operator must configure the Hamstik Microsoft Entra application; and
the Azure DevOps identity must be allowed to create and manage Service Hook subscriptions for the selected Projects.

This integration supports Microsoft-hosted Azure DevOps Services. Hamstik constructs requests only for Microsoft Azure DevOps hosts; users cannot enter an alternate server URL or a personal access token (PAT).

Microsoft Entra setup

Platform operators register a multitenant Microsoft Entra application and configure the exact callback URL:

https://hamstik.com/api/apps/azure-devops/callback

An authorized non-production deployment uses the same path on its configured canonical public origin. Configure the Entra application ID, tenant authority, and exactly one confidential-client credential mode in the deployment environment. A client secret or certificate private key is deployment secret material and must never be entered in Organization settings.

Hamstik uses the authorization-code flow with PKCE, a single-use state value, a signed Microsoft identity token, and offline renewal. It does not use deprecated Azure DevOps OAuth or PAT authentication.

Required delegated capabilities

The Entra application registration must grant the reviewed Azure DevOps delegated capabilities represented by these Azure DevOps scopes:

Capability	Purpose
`vso.profile`	Connected identity and organization discovery.
`vso.project`	Azure DevOps Project discovery and metadata.
`vso.code`	Azure Repos, refs, commits, pushes, pull requests, reviewers, and Git Service Hooks.
`vso.build`	Build and Pipelines definitions, runs, timelines, artifacts, and run events.
`vso.environment_manage`	Modern Environment and deployment-history reads. Microsoft currently maps the read endpoints to this broader capability.
`vso.release`	Classic Release definitions, releases, environments, artifacts, deployments, and events.
`vso.notification` and `vso.notification_write`	Service Hook metadata, inventory, creation, repair, test, and deletion.

Hamstik requests openid profile offline_access plus the configured Azure DevOps resource .default grant. It rejects Azure Boards, code-write, build-execute, release-manage/execute, deprecated vso.hooks*, and broad impersonation scopes.

Environment permission

Microsoft documents vso.environment_manage for the Environment read endpoints and describes inherited agent-pool management privilege. Review and approve this permission deliberately before enabling the integration. Hamstik uses it only for environment and deployment-history reads.

Connect Azure DevOps

Open Organization Settings → Apps.
Find Azure DevOps and select Connect Azure DevOps.
Sign in with Microsoft and approve the reviewed access.
If the identity can access more than one Azure DevOps organization, choose one. One Hamstik installation always represents exactly one Azure DevOps organization.
Select ADO Projects on the connection card.
Select one or more Azure DevOps Projects and choose Save selection.

Hamstik keys the connection by Azure DevOps’s stable organization/account ID, not by the mutable organization name. You can connect multiple Azure DevOps organizations to one Hamstik Organization as separate installations.

Select Azure DevOps Projects

An Azure DevOps Project is not a Hamstik Project. Organization settings define which Azure DevOps Projects the connection may ingest. Newly created Azure DevOps Projects remain unselected until an administrator explicitly selects them.

Changing the selection queues bounded synchronization and Service Hook reconciliation. Removing an Azure DevOps Project stops its active selection and removes its desired project-scoped hooks; retained historical evidence continues to follow Hamstik retention rules.

Add repositories to a Hamstik Project

After the organization catalog has synchronized:

Open a Hamstik Project and go to Project Settings → Apps.
Enable the Azure DevOps installation for that Project.
Select Choose repositories.
Choose up to 50 repositories from the selected Azure DevOps Projects.
Select Save repositories.

Only an enabled repository selection grants the Project’s development capabilities. Removing one repository selection does not remove the Azure DevOps Project from the organization connection or affect another Hamstik Project.

Synchronization

The first synchronization is deliberately bounded:

Evidence	Initial boundary
Repository commits and pushes	Previous 90 days; up to 1,000 commits and 500 pushes per repository.
Pull requests	Up to 500 active pull requests plus the 500 most recent completed/abandoned pull requests in the previous 90 days.
Builds and Pipeline runs	Previous 30 days; 500 combined executions per Azure DevOps Project.
Modern deployments	Previous 90 days; 1,000 deployment records per Azure DevOps Project.
Classic Releases	Previous 90 days; 500 releases and 1,000 deployment attempts per Azure DevOps Project.

Synchronization is asynchronous. Sync now queues a bounded pass; it does not make the browser wait for all provider requests. Hamstik stores cursors and safe watermarks so interrupted work can retry without an unbounded crawl.

Service Hooks

Hamstik creates project-scoped Service Hook subscriptions for Git pushes, pull-request changes, Build completion, Pipeline run/stage changes, and core Classic Release/deployment changes. Repository lifecycle subscriptions are used only when Azure DevOps metadata proves they can be scoped to the selected Project.

Service Hooks notify Hamstik that a resource changed. The background worker normally fetches the authoritative current state from the Azure DevOps REST API before updating stored evidence. Periodic reconciliation repairs missed deliveries and resource drift; it is not high-frequency polling.

The receiver uses HTTPS and a generated, per-installation Basic Authentication password. Azure DevOps does not provide the GitHub-style HMAC signature mechanism, so Hamstik does not claim HMAC verification for these deliveries.

Environments and deployments

Modern Azure Pipelines environments and the delivery portions of Classic Releases populate Hamstik’s provider-neutral environment and deployment records. Azure DevOps-only details remain in their lossless provider projection.

A deployment attempt can link to a Build, repository, commit, or pull request when the provider’s orchestration plan or Classic Build artifact establishes that relationship. Hamstik displays missing links as unknown; it never infers them from similar names or timestamps alone.

Classic Releases

Classic Release support includes definitions, releases, definition environments, release artifacts, and every available deployment attempt in the bounded history window. Build artifacts can establish a direct source-build and source-commit relationship. Other Classic artifact types are retained as Azure DevOps references without pretending they map to a Build.

Health and repair

The Azure DevOps connection card distinguishes connected, reauthorization required, partial access, Service Hook problems, delayed synchronization, rate limiting, provider unavailability, and missing operator configuration. It also shows selected Project, repository, and pipeline counts; hook health; pending/failed work; and last event, processing, successful-operation, and reconciliation times.

Select Test to verify identity and organization access.
Select Sync now to queue bounded catch-up.
Select Repair hooks to inventory and repair missing or system-disabled subscriptions. Hamstik never silently re-enables a hook marked disabledByUser in Azure DevOps.
Select Reauthorize when consent was revoked, expired, or granted through the wrong Microsoft identity. Reauthorization must select the same stable Azure DevOps organization.

Provider error bodies and credentials are not shown. A Project-specific permission failure can degrade that Project without making another selected Project disappear.

Disconnect

Disconnect first attempts to delete desired Azure DevOps Service Hook subscriptions, then fences queued work, removes encrypted credentials and active Project selections, and removes current installation provenance. Audit history and historical development/delivery evidence remain.

If provider access is already revoked, Hamstik records any hook subscription it could not remove for operator follow-up. Reconnecting the same Azure DevOps organization reuses its stable provider identity and does not duplicate retained environment, deployment, repository, or release evidence. Project and repository selections must be made explicitly again.

Security

OAuth state is single-use and bound to the initiating Hamstik user, Organization, operation, safe return path, and short-lived encrypted PKCE cookie.
Refresh tokens and webhook passwords are encrypted through Hamstik’s shared App secret store. Access tokens are short-lived and memory-only.
The only session-free ADO route is the exact Service Hook endpoint. Every callback and management route still requires a Hamstik session and appropriate Organization or Project permission.
The webhook endpoint requires JSON, enforces a 2 MiB body limit, verifies the opaque receiver and password, checks subscription/account/Project/event boundaries, and durably stores the event before acknowledging it.
Delivery IDs are installation-scoped. The Azure DevOps event UUID is primary; malformed legacy events use a versioned canonical payload hash. Duplicate deliveries are harmless.
Hamstik application logs and audit detail exclude or redact credentials, authorization codes, PKCE verifiers, authorization headers, cookies, and provider response bodies. Operators must also configure the separate public ingress not to retain OAuth callback query strings.

Troubleshooting

Operator configuration required

The Hamstik deployment is missing or has malformed Entra configuration. Contact the platform operator. Do not create a PAT or paste a client secret into Hamstik.

Reauthorization required

The delegated refresh grant was revoked, expired, or blocked by Conditional Access. Select Reauthorize, sign in with an identity that can access the same Azure DevOps organization, and complete consent.

Partial access

The connected identity cannot access one or more selected Azure DevOps Projects or capability areas. Check Azure DevOps membership and the reviewed Entra permissions, then use Test, ADO Projects, and Sync now. Do not add Azure Boards permission to solve a Repos, Build, Environment, Release, or Service Hook failure.

Service Hooks need attention

Select Repair hooks. If a hook is disabled by a user in Azure DevOps, either re-enable it there intentionally or leave it disabled; Hamstik respects that choice. Verify that the public Hamstik origin is reachable over HTTPS with a valid certificate.

Delivery evidence is delayed

Check pending/failed counts and the last processed event. Azure DevOps throttling and temporary outages are retried with bounded backoff. Use Sync now after the provider recovers.

A repository is missing from Project Settings

Confirm that its Azure DevOps Project is explicitly selected in Organization Settings, allow catalog synchronization to complete, then reopen Choose repositories. A repository newly created in an unselected Azure DevOps Project is intentionally not discovered.

For related concepts, see Applications, Projects, and Work Items.