SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillspipelines-approvals

pipelines-approvals

Deployment & operations

View repository

Updated 10-15 21:11

About this skill

Pipeline approvals

This Skill is from theapprover'sperspective, handling approvals on environments or resources in YAML Pipelines (Approvals and Checks): find items waiting for my approval, understand what they are about to deploy, and respond to them. For adding or modifying approvers and checks settings, ask the user to do it in the web UI.

Project selection

  • If the user provides a project name (for example "Contoso project"), use it directly and do not call the project list API.

  • If it is not provided, ask the user to provide it once.

  • If it is still not provided, list projects for the user to choose:

    curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/_apis/projects?%24top=500&api-version=7.1"

  • The approvals API has no organization-level endpoint, so a project must be specified. When the user wants "all projects", repeat rule 1 for each project in the list; if there are more than 20 projects, first tell them the count and confirm once.

  • Do not continue until the user provides or selects a project.

Connection and authentication

Always use curl to call the Azure DevOps REST API directly, with authentication parameters on every command.

  • Organization: read the environment variable AZURE_DEVOPS_ORG(organization name, for example contoso). If it is not set, ask the user once; if the user gives a URL, extract the organization name from https://dev.azure.com/{org} or https://{org}.visualstudio.com .
  • Host: besides dev.azure.com, the Identities API host for querying group members is vssps.dev.azure.com。
  • Token: send the PAT with Basic authentication:-u ":$AZURE_DEVOPS_PAT"; if only AZURE_DEVOPS_EXT_PATis set (the variable used by the Azure CLI azure-devops extension), use that instead. When using a Microsoft Entra ID token instead, switch to -H "Authorization: Bearer $AZURE_DEVOPS_TOKEN". If neither is set, ask the user to set AZURE_DEVOPS_PAT in their own terminal and retry, then stop. Read tokens only from environment variables: do not ask the user to paste the token into the chat, and do not print it or write it to a file.
  • PAT scopes: listing and mapping runs requires Build (Read) and Identity (Read); approving or rejecting additionally requires Build (Read & execute) and Pipeline Resources (Use) (Microsoft Learn's Approvals - Update lists these two scopes).
  • Encoding: project names in the path must be URL-encoded (write spaces as %20); write $ in the query string as %24(for example %24expand) to avoid shell expansion.
  • Errors: HTTP 401, 403, 203, or an HTML login page response means the token is invalid, expired, or has insufficient permissions; report and stop. HTTP 404 means the organization, project, or approval ID is wrong. When approve or reject fails, show the user the original error message (common causes: I am not an approver for that step, in blockedApprovers , or the approval is no longer pending）。
  • Windows PowerShell: call curl.exe(instead of the curl alias), write the environment variable as $env:AZURE_DEVOPS_PAT; PowerShell does not support <<'EOF', so first write the JSON body to a temporary file, then send it with --data-binary "@body.json" .

Current user

Rule 1 requires the current user's identity ID (this endpoint does not carry api-version）：

curl -sS -u ":$AZURE_DEVOPS_PAT" "https://dev.azure.com/$AZURE_DEVOPS_ORG/_apis/connectionData"

Use authenticatedUser.id；authenticatedUser.providerDisplayName is the display name.

Rules

1. List items waiting for my approval

  1. Get pending approvals in a project. You must include %24expand=steps, otherwise steps is an empty array; add permissions to know whether I can act on them:

    curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/pipelines/approvals?state=pending&%24expand=steps,permissions&api-version=7.1"
    • Each has id、status、instructions(approval description),minRequiredApprovers、executionOrder（anyOrder or inSequence）、blockedApprovers、createdOn, and pipeline(see Rule 2).
    • steps[] is for each approver:assignedApprover（id、displayName、descriptor）、status、permissions、comment。
    • The parameter that limits the number of records is top(without $); without state it returns all statuses. Do not rely on userIds for filtering; always compare locally.

  2. Determine which are "mine":

    • Direct assignment：steps[].assignedApprover.id equals my ID, and that step's status is pending。

    • Via group：assignedApprover.descriptor starting with vssgp. or aadgp. (or with isContainer equal to true) is a group. Get my direct group memberships (memberOf is a list of group descriptors):

      curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://vssps.dev.azure.com/$AZURE_DEVOPS_ORG/_apis/identities?identityIds={myId}&queryMembership=Direct&api-version=7.1"

      Then use identityIds={groupId1},{groupId2} to look up these groups' descriptorin one go; those appearing in my memberOf count as "waiting for my approval via {group name}".

    • steps[].permissions or the whole entry's permissions containing updatemeans I can currently act on it; when there is only view , list it but mark it "cannot act".

    • When I appear in blockedApprovers (for example, approving a run that I triggered is not allowed), mark it "You are excluded and cannot approve".

    • executionOrder is inSequence , only the step with the smallest order that is still pending can be acted on;status is uninitiated means the step's turn has not come yet.

    • assignedApprover.displayName is null , the identity cannot be resolved; list the ID and mark it "unrecognized approver".

  3. Apply Rule 2 to each "my" approval to add the Pipeline, run, and stage.

  4. When there are no pending approvals, clearly state that there are no items waiting for my approval.

Examples: "Which deployments in the Contoso project are waiting for my approval?", "Are there any stages waiting for my approval across all projects?"

2. Map the Pipeline, run, and stage

  • The approval object's pipeline fields (not listed in the Microsoft Learn model, but actually returned):pipeline.id and pipeline.name are the Pipeline,pipeline.owner.id is the run (build) ID,pipeline.owner.name is the build number,pipeline.owner._links.web.href is the web link.

  • When you need the branch and requester, get the build (sourceBranch、requestedFor.displayName、sourceVersion）：

    curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/build/builds/{buildId}?api-version=7.1"

  • Find the stage: get the timeline for that build,records[] where id equals the approval ID,type is Checkpoint.Approval(when pending, state is inProgress). Its parentId points to type as Checkpoint record, and one level up, the parentId is the type record where Stage isname is the stage display name,identifier is the stage identifier name:

    curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/build/builds/{buildId}/timeline?api-version=7.1"

    Under the same Checkpoint , records such as Checkpoint.TaskCheck、Checkpoint.ExtendsCheck are other checks; when they are state or pending , it means that after approval, these checks still need to pass.

  • When the approval object has no pipeline , list the running builds (GET .../_apis/build/builds?statusFilter=inProgress&api-version=7.1), retrieve the timeline for each, and find records where id equals the approval ID; if none are found, mark "cannot map to a run" and do not guess.

  • From a run to an approval (user asks "why is build 12345 stuck"): conversely, in the timeline, find the record where type is Checkpoint.Approval and state is inProgress , and use its id to look up the approval:

    curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/pipelines/approvals/{approvalId}?%24expand=steps&api-version=7.1"

Example: "Which stage is build 12345 stuck at waiting for whose approval?"

3. Approve or reject (write)

  1. List the content about to be submitted to the user, and execute only after one confirmation: Pipeline name, build number (link), branch and commit, stage, approval description (full text ofinstructions ), requester, decision (approve or reject), and full comment. If the user has not provided a comment, ask once; if still none, leave it blank. Rejection will cause that stage to fail, so give a special reminder.

  2. Submit (status is approved or rejected; the array can process multiple entries at once, but each entry must be confirmed first):

    curl -sS -u ":$AZURE_DEVOPS_PAT" -X PATCH -H "Content-Type: application/json" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/pipelines/approvals?api-version=7.1" \
  -d '[{"approvalId":"{approvalId}","status":"approved","comment":"已確認變更內容，同意部署。"}]'

  3. Check the statusof that approval in the response: if it is still pending , it means other people are still needed (minRequiredApprovers is greater than the number of people who have approved); explain how many more are needed; if it becomes approved or rejected , it means it has taken effect. To track the run afterward, use pipelines-run。

Reassigning approvers (reassignTo) and deferred approval are out of scope; ask the user to operate on the web page.

Example: "Approve the deployment of MyApp-CD at the Production stage", "Reject the deployment of build 12345 because QA has not passed"

Present the results

Display times in the user's local time zone (format YYYY/MM/DD HH:MM); when the time zone cannot be determined, indicate UTC. The build link format is https://dev.azure.com/{organization}/{project}/_build/results?buildId={buildId}; remove refs/heads/。

Pending approval listPresent as a table:

  • Pipeline（pipeline.name) andBuild number(clickable link)
  • Branch、Stage(display name)
  • Assignment method: 👤 directly assigned to me, or 👥 via {group name}
  • Progress: number approved /minRequiredApprovers，inSequence indicates order when
  • Waiting time: calculated from createdOn (for example, "3 hours")
  • Description：instructions first line of
  • Can handle: ✅ can handle, 👀 view only, ⛔ excluded

After approvalReport back: ✅ approved or ❌ rejected, my comment, the final status of the approval, and how many more approvers are needed.