subscription-history

# Subscription History Tell the history of a Maestro subscription — what happened each time it was triggered — using `darc get-subscription-history`. Each result is a **subscription trigger outcome** recorded by Maestro describing what happened when a subscription ran (a PR was opened/updated, there was nothing to update, the update failed, etc.). ## When to Use This Skill Use this skill when the user wants the **history** of a subscription's trigger outcomes — for example: - "Show me the history of subscription `<guid>`" - "Why has this subscription been failing?" - "Did this subscription open a PR in the last week?" - "What were the last 5 outcomes for the core-sdk subscription?" Do **not** use this skill for current staleness/health (use `flow-analysis` or `maestro-cli`), for tracing a commit across repos (use `flow-tracing`), or for CI build failures (use `ci-analysis`). ## Inputs - **darc** installed and authenticated (see below). - One or more filters describing the subscription of interest. The most precise filter is the subscription id (GUID). If the user gives a repo/branch instead, use `--search` or first resolve the id with `darc get-subscriptions`. ## Prerequisites `darc` (Dependency ARcade) manages dependency flow in the .NET ecosystem. 1. Install (or update) from any arcade-enabled repo by running the `darc-init` script in `eng/common`: ```powershell .\eng\common\darc-init.ps1 # Windows ``` ```bash ./eng/common/darc-init.sh # macOS / Linux ``` This installs the version of darc the repo expects; re-run it to update an out-of-date darc. 2. Authenticate once: `darc authenticate` (caches Entra ID credentials under `~/.darc/`). Required to read Maestro/BAR data. Verify with `darc get-subscription-history --help`. If the command is not recognized, the installed darc is too old — re-run `darc-init` to update it. ## Workflow ### Step 1: Identify the subscription The most precise filter is the subscription id. If the user provided one, use `--id <guid>`. Otherwise, resolve it: ```bash # Find the subscription id from the source/target repos darc get-subscriptions --source-repo <source> --target-repo <target> ``` You can also skip resolution and pass a `--search` term that is matched against the subscription's source repo, target repo and target branch. ### Step 2: Query the history ```bash # Full history of one subscription (most recent first) darc get-subscription-history --id <subscription-guid> # Narrow to failures only darc get-subscription-history --id <subscription-guid> --type Failure # By repo/branch free-text search instead of id darc get-subscription-history --search core-sdk --limit 5 # Outcomes produced by a specific build darc get-subscription-history --build <bar-build-id> # Restrict to a date range (ISO 8601, treated as UTC) darc get-subscription-history --id <guid> --after "2025-01-01T00:00:00Z" --before "2025-02-01T00:00:00Z" # Machine-readable output for scripting/jq darc get-subscription-history --id <guid> --output-format json ``` All filters can be combined. ### Step 3: Interpret and report Each text outcome looks like: ``` 2025-01-15 12:34:56Z [Failure] build 1234567 Subscription: https://github.com/dotnet/runtime ==> 'https://github.com/dotnet/dotnet' ('main') Subscription Id: 510286a9-8cd5-47bd-a259-08d68641480a PR: https://github.com/dotnet/dotnet/pull/4242 Failed to update dependencies: <details> ``` Summarize for the user: the timeline of outcomes (newest first), how many of each `[Type]`, any recurring failures with their messages, and links to the PRs that were opened. Outcome types: | Type | Meaning | |------|---------| | `Updated` | Dependencies were updated; a PR was opened or updated. | | `NoUpdate` | Nothing to update — already current. | | `NotUpdatable` | The subscription could not be updated (e.g. config issue). | | `Failure` | The update attempt failed. Read the message for the cause. | | `UserError` | Failure caused by user/config input. | | `HasConflict` | A merge conflict blocked the update. | | `Rescheduled` | The update was deferred and will retry. | ## Options Reference | Option | Description | |--------|-------------| | `--id` | Filter by subscription id (GUID). | | `--build` | Filter by the BAR build id that triggered the outcome. | | `--type` | Filter by outcome type (`Updated`, `NoUpdate`, `NotUpdatable`, `Failure`, `UserError`, `HasConflict`, `Rescheduled`). | | `--search` | Free-text match against source repo, target repo and target branch. | | `--after` / `--before` | Restrict to outcomes on/after or on/before a date (e.g. `"2025-01-15T12:00:00Z"`). | | `--limit` | Max outcomes to return (1-1000, default 10). | | `--output-format` | `text` (default) or `json`. | ## Validation - `darc get-subscription-history --help` lists the verb and options → darc is current and authenticated. - A successful run prints one or more outcome blocks (text) or a JSON array. - "No subscription trigger outcomes found matching the specified criteria." means the filters matched nothing — broaden `--search`/date range or confirm the `--id` is correct via `darc get-subscriptions`. ## Common Pitfalls - **GUID, not repo name, for `--id`.** A non-GUID value errors out. Use `--search` for repo/branch text matching. - **Dates are UTC, ISO 8601.** Use a form like `"2025-01-15T12:00:00Z"`. - **Default `--limit` is 10.** Increase it to see deeper history. - **Old darc.** If the verb is unknown, re-run `eng/common/darc-init.ps1` (or `.sh`) to update darc — the command was added recently.