agentleFS
ridermwridermw/my-skills/skills/ado-pr-build-monitor/SKILL.md

ado-pr-build-monitor

Skill0 starsChanged 2 months agoMITView on GitHub

Use when the user wants to monitor or watch an Azure DevOps (ADO) pull request build to completion — "monitor PR [url] and let me know when the build completes", "watch this PR build", "tell me when the PR build passes and a work item is linked", "is the PR gate green yet", ADO PR build/policy/gate status polling. Read-only; reports status, does not post comments or complete the PR.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the user keeps separate Azure profiles for different tenants, they can scope the login with AZURE_CONFIG_DIR (for example …

    line 53
  2. Very specific:

    If a needed capability has no MCP tool, use the Azure CLI with the azure-devops extension: az repos pr show, az repos pr policy list, az …

    line 73
  3. Distinctive:

    If no authenticated read capability is available, report that and stop.

    line 91
  4. Distinctive:

    Check that deadline before each poll/wake and bound waits and request timeouts by the remaining budget.

    line 98
  5. Distinctive:

    If builds will take many minutes, do not sit in a tight sleep loop for the whole duration.

    line 179
  6. Distinctive:

    If your runtime has no scheduling facility, report the current status, state clearly that monitoring has paused, and offer to resume on …

    line 187
  7. Very specific:

    Always keep the original hard max wait cap.

    line 191
  8. Distinctive:

    Use the runtime's documented creation API.

    line 193
  9. Distinctive:

    Read-only. No PR comments, votes, completion, or work-item creation unless the user explicitly asks in this session.

    line 198
  10. Distinctive:

    Never approve or complete a PR automatically, even if all gates are green.

    line 200
  11. Distinctive:

    If auth or a tool is unavailable, say so plainly and stop — do not guess build status.

    line 201

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ADO PR Build Monitor

Watch an Azure DevOps pull request's build/policy gates until they reach a terminal state, confirm a work item is linked, and report the outcome. On a build failure, surface the failing stage and the root-cause lines from the log so the user can act immediately.

This is a read-only monitor. It does not comment on the PR, vote, complete, or create work items. If the user also wants a code review or PR write-backs, that belongs to a separate code-review skill — keep this one focused on "watch and report."

Throughout, a required build is a build the PR's branch policy requires. The ADO API exposes these as policy evaluations that point at a pipeline run; "gate" is used loosely for the same thing. Prefer "required build" in your report so the user is not left mapping three names onto one object.

When to use

  • "monitor PR [url] and let me know when the PR Build is completed and a work item has been linked"
  • "watch the build on this PR" / "ping me when the gate is green"
  • Checking build and work-item conditions on an ADO PR. Full merge readiness requires other policies too; passing these checks alone does not prove it.

Inputs

  • PR URL (required). Both Azure DevOps URL forms are supported:

    • https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{id}
    • https://{org}.visualstudio.com/{project}/_git/{repo}/pullrequest/{id} (legacy)

    Parse org, project, repo, and numeric prId. If the URL is missing the project segment (some orgs collapse it when project == repo), resolve the project from the repo before continuing rather than guessing.

  • max wait (optional): default cap ~45 min. Never poll forever.
  • poll interval (optional): default 60–120s.

Authentication

Azure DevOps access is via whatever Azure CLI / MCP credential the environment already uses. If the first ADO call returns an auth error, ask the user to sign in and wait for them to confirm before retrying:

az login

If the user keeps separate Azure profiles for different tenants, they can scope the login with AZURE_CONFIG_DIR (for example AZURE_CONFIG_DIR=~/.azure-work az login; on Windows, $env:AZURE_CONFIG_DIR = "$env:USERPROFILE\.azure-work"). Use the same AZURE_CONFIG_DIR for every subsequent call in the session. Never guess a profile path — ask which one to use.

Tool discovery

Azure DevOps access is normally provided by the official Azure DevOps MCP server, whose tools are prefixed azure-devops-* (a.k.a. ado-*). Tools may be deferred or lazily loaded, so search first (if your runtime has a tool-search facility) for azure-devops|ado|pull_request|build|pipeline|work_item, then pick the ones for:

  • get pull request by id (title, status, source/target branches and revisions)
  • list current PR policy evaluations, including configuration and run context
  • get build / pipeline run status + logs for the build id the policy points to
  • list PR work-item refs (linked work items)

If a needed capability has no MCP tool, use the Azure CLI with the azure-devops extension: az repos pr show, az repos pr policy list, az repos pr work-item list, az pipelines runs show, and az boards work-item show. Supply the resolved organization/project explicitly.

There is no az pipelines runs tail command. Use the authenticated REST transport available in the environment (az devops invoke is one option) for GET-only log retrieval:

GET /{project}/_apis/build/builds/{buildId}/timeline?api-version=7.1
GET /{project}/_apis/build/builds/{buildId}/logs?api-version=7.1
GET /{project}/_apis/build/builds/{buildId}/logs/{logId}?startLine={start}&endLine={end}&api-version=7.1

These paths are relative to https://dev.azure.com/{org}. Use the timeline's failed task/job records and their log IDs; get line counts from the log list, then fetch a bounded range. See the official Build Log API. If no authenticated read capability is available, report that and stop. Never queue/re-evaluate a policy or build to obtain fresh status.

Procedure

  1. Set one deadline and resolve the PR. Record start time and an absolute deadline from max wait; neither a new push nor a scheduled wake resets it. Check that deadline before each poll/wake and bound waits and request timeouts by the remaining budget. Fetch title, status, source/target branches, and current source/target commit IDs (for example lastMergeSourceCommit.commitId and lastMergeTargetCommit.commitId). A completed or abandoned PR is terminal.
  2. Refresh associations on every poll. Re-fetch the PR and all current policy evaluations, following continuation pages. Identify enabled, blocking Build policies and their current evaluation/run IDs; exclude disabled, optional, and notApplicable evaluations from required-build success. Replace cached associations when the PR revisions, policy set, evaluation, or run changes. A newly queued evaluation without a run ID is pending, not absent or successful. Do not select a pipeline's last successful run.
  3. Read the currently associated runs. Build status describes lifecycle (notStarted, inProgress, cancelling, postponed, completed); result describes the completed outcome. A run is terminal only when status: completed. Do not equate cancelling with canceled. A success candidate needs both result: succeeded and the current required policy evaluation's status: approved. Queued/running evaluations remain pending; rejected/broken evaluations are not success. PR validation can build a synthetic merge commit, so do not demand raw build.sourceVersion == PR source SHA equality. Establish relevance through the current policy evaluation's run association and PR revisions. If that association cannot be established, report it as unverified.
  4. Check linkage according to the request. List linked work items (all pages) and obtain titles when available. A link is required when an enabled, blocking work-item policy applies or the user explicitly asked for both a passing build and a linked item. Otherwise linkage is informational and never a reason to keep polling. When policy-required, also check that evaluation's approval rather than inferring it from a listed item alone.
  5. Confirm all evidence used for a terminal report. Re-read PR revisions, current required evaluations, and all linked-item references when step 4 requires linkage. If the revision, policy set, run association, relevant evaluation state, or required linked-item reference set changed, discard the candidate result and continue from step 2 within the original deadline. A startup run's success is not evidence for a new push or expired validation. Apply this confirmation to failed, partially succeeded, and canceled runs too, so a superseded failure does not terminate the current monitor.
  6. Evaluate the confirmed snapshot:

    ConditionAction
    All applicable required builds completed/succeeded and their evaluations approved; any required linkage satisfiedReport requested checks passed, not "PR ready".
    Current run completed/failedStop immediately; report failure and relevant timeline/log evidence, even if another build is still running.
    Current run completed/partiallySucceededStop with partially succeeded — required build not passed; inspect warning/failing tasks and bounded logs.
    Current run completed/canceledStop with canceled — required build not passed; include an observed cancellation reason, or say unavailable.
    Required evaluation rejected/brokenReport the policy failure and its diagnostic; do not override it with a green run.
    Completed run has missing/unknown result, or association is unverifiedReport unverified, never success; name the missing evidence.
    Builds passed but required linkage is missing/pendingFlag that condition. Keep polling only if the user asked to wait for both; otherwise report and stop.
    Builds/evaluations still pendingWait the poll interval and restart at step 2.
    No applicable required buildsReport that explicitly, not vacuous build success; monitor linkage alone only if explicitly requested.
    Deadline reachedReport timeout and last observed states with their timestamps; stop.

    Other branch policies can still block completion. This monitor does not certify full PR readiness. On failure, show the failing stage/job and at most ~15 relevant, redacted log lines as a root-cause hint, not a full log dump.

  7. Report using this shape:

    PR <id>: <title>  <link>
    Observed: <timestamp>  Source: <commit>  Target: <commit>
    Outcome: <requested checks passed | failed | partially succeeded | canceled | pending | unverified | timed out | PR closed | no required builds>
    Required builds:
      <name>  <status>/<result>  policy: <state>  <duration>  <link>
    Work items (<required | informational>): <id> <title>   (or: none linked yet)
    Next action: <one line>

    On failure, add the stage/job and relevant log lines beneath its build row. The title labels the requested change; build status does not verify that its implementation matches that goal.

Output length

Report the outcome, not the journey. While polling, stay quiet — one line when you start and one line if you pause is enough; do not narrate each poll or each unchanged status. The final report is the shape above and nothing more: no restated PR description, no full log dump beyond the root-cause lines, no closing summary of what you just said.

Long builds — don't block the session

If builds will take many minutes, do not sit in a tight sleep loop for the whole duration. In order of preference:

  • Poll a bounded number of times, then create a scheduled re-check if supported. Persist the PR identity, request/linkage condition, interval, original start time/deadline, and last observed revision/evaluation/run associations. Claim a future re-check only after scheduling succeeds. On wake, restart at step 2; do not resume polling only the old build IDs.
  • If your runtime has no scheduling facility, report the current status, state clearly that monitoring has paused, and offer to resume on request. Do not silently stop watching.

Always keep the original hard max wait cap. Cancel the monitor's schedule when the PR closes, a terminal report is produced, or the deadline expires. Use the runtime's documented creation API; a wakeup primitive for an existing loop does not itself create a monitor.

Safety

  • Read-only. No PR comments, votes, completion, or work-item creation unless the user explicitly asks in this session.
  • Never approve or complete a PR automatically, even if all gates are green.
  • If auth or a tool is unavailable, say so plainly and stop — do not guess build status.

Stop condition

Done when a confirmed terminal outcome in step 6 or PR closure is reported, or the original deadline expires. Pending builds continue at the configured interval; pending required linkage continues only when waiting for both was requested. Every stop has a final report and any monitor-owned schedule is canceled.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.