Azure Pipelines adapter

The Azure DevOps adapter turns Azure Pipelines events into Prodgator runs, deployments and approvals, and evaluates Azure Repos pull requests. To set it up, see Connect Azure DevOps.

What Prodgator supportsCopy Anchor Link

• Runs, stages and jobs from Azure Pipelines, with logs and artifacts. A run that finishes with warnings shows Succeeded with issues.
• Stages in order with their jobs. Azure DevOps does not report which stage depends on which, so Prodgator draws the stages in order, each one after the one before it.
• Deployments to Azure DevOps environments, on the Gates board.
• Cancelling a run and re-running its failed jobs. Azure Pipelines retries a whole stage, so there is no single-job re-run.
• Rollback: running an earlier deployment's stage again.
• Native approvals and checks on an environment, shown in Prodgator and answered in Azure DevOps.
• The Prodgator gate: a check on an environment that holds deployments until Prodgator answers.
• Pull request gates: the Prodgator Policies status and comment on Azure Repos pull requests, and Require on a branch from Prodgator.
• Policy files in the repository (.prodgator/policies/), synced when you push to the default branch.
• Run reports from the Prodgator task or the command line.
• AI release risk, and the people and system metrics in SPACE metrics. Release risk reads file names and change types, not line changes, because Azure Repos does not return them.
• Linked Azure DevOps accounts, for attribution and for running stages as you.

Azure DevOps cannot redeliver events, so Prodgator recovers missed ones itself: a background pass lists the builds that changed since its last look and fills any gap. The same pass adds hooks to projects created after you connected.

If you rename the organization in Azure DevOps, Prodgator picks up the new name when its token next refreshes or when the old address stops working. Projects and repositories are tracked by id, so renaming them breaks nothing.

EventsCopy Anchor Link

Prodgator creates one service hook per project and event, nine per project. Each delivers to https://api.prodgator.io/api/webhooks/azure/{connection id}.

Webhook verificationCopy Anchor Link

Azure DevOps cannot sign deliveries. Each connection has its own random secret, which Azure DevOps sends as the Basic authentication password over HTTPS. Prodgator checks it, and checks that the delivery names the connection's own Azure DevOps organization. A request that fails either check is refused.

Connect with a personal access tokenCopy Anchor Link

Use a personal access token (PAT) when the Microsoft sign-in cannot work: the organization uses personal Microsoft accounts (outlook.com, hotmail.com), or your Microsoft Entra tenant does not allow the sign-in. Open Admin Console > Integrations > Azure DevOps and choose Use a personal access token. Only admins can connect.

Create the token in Azure DevOps under User settings > Personal access tokens > New token. Set Organization to the one you are connecting, choose Custom defined, and select Show all scopes:

Paste the token in Prodgator with the organization name and the expiry date you chose. Prodgator cannot read a token's expiry from Azure DevOps, so it asks you for it. The date must be between tomorrow and a year from today.

Prodgator checks the token against your organization before it saves anything. It refuses a token that is missing a read scope, a Microsoft sign-in token instead of a personal access token, and a token with more access than it needs. If you picked Full access, create a new token with only the scopes above. The token acts as the person who created it, so keep it narrow.

Prodgator keeps the token encrypted, never shows it again, and never writes it to a log. The Integrations page shows Personal access token, the owner's name and the expiry date.

Expiry and remindersCopy Anchor Link

Prodgator sends a notice 14 days and 3 days before the expiry date, to the organization and to the admin who connected the token. An expired notice goes out once, within 7 days after the date. When the token expires, or when Azure DevOps refuses it, the connection shows a Reconnect required badge. Under it the card reads Expired with the date once it has passed, or Refused by Azure DevOps: replace the token when Azure DevOps refuses the token before that date. Prodgator sends nothing with the token until you replace it, and Find my Azure DevOps account is hidden for that connection until then.

Replace the tokenCopy Anchor Link

Create a new token with the same scopes, then choose Replace token on the Azure DevOps card and paste it with its expiry date. You can also connect the same organization again with a token or with the Microsoft sign-in: the new credential takes over, and the hooks move across without a gap. Reminders start again for the new expiry date.

Prodgator cannot revoke a token. After you replace or disconnect, revoke the old one in Azure DevOps under User settings > Personal access tokens.

What differs from the Microsoft sign-inCopy Anchor Link

Re-run, cancel and rollback only work on runs whose connection still exists in this Prodgator organization, and always use that connection's organization.

One-time setup tokenCopy Anchor Link

Protecting an environment on Gates, or requiring Prodgator Policies on a branch, needs scopes the kept token does not have. On a token connection the dialog asks for a second token with these scopes: Environment: Read & manage; Service Connections: Read, query & manage; Pipeline Resources: Use & manage; Code: Read, write & manage. Create it with a 1 day expiry and revoke it afterwards. Prodgator checks it belongs to the same organization, uses it once, and deletes it within the hour. The by-hand steps stay available.

Link your Azure DevOps account by emailCopy Anchor Link

In an organization backed by personal Microsoft accounts, people link their account without a sign-in. Open Profile > Linked accounts and choose Find my Azure DevOps account. Prodgator searches the organization for your Microsoft sign-in name, which must match your Prodgator email, and the email must be verified. A contact email in Azure DevOps does not count. It shows the account it found, and you confirm before it links.

This is offered only in organizations connected with a token where every member signs in with a personal Microsoft account. It is refused if you already linked Azure DevOps with the Microsoft sign-in. Once linked, your name shows on approvals and pull request reviews.

Permissions Prodgator asks forCopy Anchor Link

Prodgator asks Microsoft for these Azure DevOps scopes when you connect. Your Microsoft Entra admin may need to approve them once for the tenant.

Two other sign-ins ask for their own scopes.

Status mappingCopy Anchor Link

The Prodgator gateCopy Anchor Link

The gate holds deployments to an Azure DevOps environment until Prodgator answers. It is a built-in Invoke REST API check on the environment, set to wait for a callback, plus a Generic service connection named Prodgator that carries the connection's check secret.

To add it, open Gates, choose Protect an Azure DevOps environment, pick the project and the environment, and sign in to Microsoft once. You must be an Administrator of that environment in Azure DevOps. Prodgator creates the connection and the check, then discards the sign-in. The dialog also shows the steps to create both by hand.

After that:

1. A run reaches the environment and Azure DevOps runs the check, which tells Prodgator.
2. The deployment shows on Gates > Awaiting approval as awaiting approval in Prodgator.
3. Someone approves or rejects it in Prodgator, or an enforce release policy bound to the environment decides it. Approved, the stage continues. Rejected, the stage fails.

A gate stays open for at most 47 hours. Azure DevOps lets a check's token live 48 hours, so Prodgator closes the gate as expired an hour before that. The check itself times out after 48 hours, so if Prodgator is down, Azure DevOps skips the stage on its own.

See Approve deployments for who can answer.

Native approvalsCopy Anchor Link

An environment can also hold a deployment with Azure DevOps' own approvals and checks. Prodgator shows who must approve, the status and an Approve in Azure DevOps link. It has no Approve button for these: you decide in Azure DevOps and the result shows in Prodgator. Prodgator never approves, rejects or forwards a native approval.

To get a Prodgator approval on top of a native one, add the Prodgator gate to the same environment. Azure DevOps runs both.

Linked accountsCopy Anchor Link

Link your Azure DevOps account under Profile > Linked accounts. Prodgator then:

• names you on approvals and runs where Azure DevOps names you;
• cancels runs, re-runs failed jobs and rolls back as you, so Azure DevOps records you as the person who did it.

Without a linked account, these actions ask you to link one first. A re-run or rollback passes the environment's approvals and checks again.

Pull request gatesCopy Anchor Link

Prodgator posts one pull request status, genre prodgator and name policies (shown as prodgator/policies), on the pull request's latest iteration, and keeps one comment thread with the results. The status is pending while a rule waits, failed when a blocking rule fails, succeeded otherwise and not applicable when no policy applies. Azure DevOps has a neutral state, so a pull request no policy gates is not blocked.

To block a merge, require the status on the target branch. On a pull request, open Merge protection and choose Require Prodgator Policies on the branch: one Microsoft sign-in creates a Status check branch policy. Or add it by hand under Project settings > Repositories > Policies > Status checks, with genre prodgator and name policies, set to Required. See Pull request gates.

Run reportsCopy Anchor Link

Run reports use the pipeline's job token, because Azure DevOps has no OIDC token Prodgator can verify. Prodgator checks the token with Azure DevOps once and discards it. See Run reports. Do not run the ghcr.io/prodgator/report image as an Azure Pipelines container job: it is Alpine with its own entrypoint, and Azure DevOps needs to install its agent tools in a job container. Use the task, npx, or a script step that runs the image with docker run (shown there).

What is not availableCopy Anchor Link