Deployment PlaybookDocsSign inGet started

Azure DevOps integration

Available on: Team and above for connecting, plans from tags and Git statuses. Business and Enterprise for the environment check, in both ApiResponse and Callback mode. On lower plans the check answers status: "rejected" with the reason "Requires Business plan" (fail closed), and in Callback mode it completes as failed. After a downgrade, connections are kept but gated features stop being processed. See pricing.

Works with Azure DevOps Services (https://dev.azure.com/<org>) and Azure DevOps Server over https.

  • Tag push → plan. A Code pushed service hook creates a plan from the mapped template when a matching tag is pushed. You get one plan per repository and tag; redeliveries are ignored. Annotated tags are resolved to their commit.
  • Git status. The tagged commit gets a deployment-playbook/release status that links to the plan: pending while sign-off runs, succeeded when the plan is done, failed when it's rejected, error when it's rolled back.
  • Environment check. An Invoke REST API check on a pipeline environment keeps deployment jobs waiting until the plan's gate phase is open.

1. Create a personal access token

Go to User settings → Personal access tokens → New token and pick the organization. Use a service account if you have one.

Scope Why
Code: Read & status (vso.code_status) Resolve annotated tags, post commit statuses

The token is stored encrypted (AES-256-GCM). Renew it on the Integrations page before it expires.

2. Connect the workspace

Under Integrations → Azure DevOps (Admins only), enter the organization URL (for example https://dev.azure.com/acme, or https://tfs.example.com/DefaultCollection for Server) and the PAT, then click Connect. The page then shows the service hook URL, the environment check URL and a password.

Azure DevOps Server must be reachable over https on a public address. Private and reserved IP ranges are refused, so a server that is only reachable inside your network can't be connected yet.

3. Add the service hook

  1. In the project, go to Project settings → Service hooks → + → Web Hooks.
  2. Trigger: Code pushed. Pick the repository (or [Any]). Leave the branch filter empty, because tags have no branch.
  3. URL: the service hook URL. Basic authentication username: playbook. Password: the password from the Integrations page.
  4. Resource details to send: All.

4. Map repositories

Add a mapping with Project/Repository (for example Shop/web), the template, the tag pattern (default v*), the environment, the gate phase and the four-eyes setting.

5. Gate the environment

  1. Create a service connection: Project settings → Service connections → New → Generic.
    • Server URL: https://deployment-playbook.com/
    • Username: playbook
    • Password: the password from the Integrations page.
  2. Open Pipelines → Environments → production → Approvals and checks → + → Invoke REST API and set:
    • Connection type: Generic, using the service connection above.
    • Method: POST.
    • URL suffix: api/integrations/azure-devops/check/<id> (copy it from the Integrations page).
    • Body:
{ "repository": "$(System.TeamProject)/$(Build.Repository.Name)", "sha": "$(Build.SourceVersion)", "ref": "$(Build.SourceBranch)" }
  1. Pick one of two completion modes:
    • ApiResponse (simplest). Set the success criteria to eq(root['status'], 'approved') and a time between evaluations of 5 to 10 minutes. The check answers pending until the gate phase is open, and Azure DevOps keeps re-evaluating.
    • Callback (immediate). Set Completion event to Callback and add these headers:
{
  "Content-Type": "application/json",
  "PlanUrl": "$(system.CollectionUri)",
  "ProjectId": "$(system.TeamProjectId)",
  "HubName": "$(system.HostType)",
  "PlanId": "$(system.PlanId)",
  "JobId": "$(system.JobId)",
  "TaskInstanceId": "$(system.TaskInstanceId)",
  "AuthToken": "$(system.AccessToken)"
}

 Deployment Playbook stores the job's callback token encrypted. When the gate decides, it posts a
 `TaskCompleted` event (*succeeded* or *failed*) back to your organization, then deletes the token. Callbacks
 are only sent to the organization you connected.

A deployment job that targets the environment then waits:

trigger:
  tags:
    include: ["v*"]
stages:
  - stage: Deploy
    jobs:
      - deployment: web
        environment: production   # waits for the Deployment Playbook check
        strategy:
          runOnce:
            deploy:
              steps:
                - script: ./deploy.sh

If no plan exists for the repository and commit, the check answers rejected.

Security

  • The service hook and the check endpoint require the connection password (HTTP Basic, or the header X-Playbook-Secret).
  • Both are rate-limited per connection. Service-hook deliveries are de-duplicated by event id.
  • Outbound calls go only to the organization URL you configured, through the SSRF guard.
  • Disconnect deletes the stored PAT. Also revoke the PAT and remove the service hook in Azure DevOps.
← GitLab integration