514cf68af1Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b8535f33-08ac-44ef-84d1-aab96770ae3a
190 lines
11 KiB
Markdown
190 lines
11 KiB
Markdown
---
|
|
name: verify-release
|
|
description: Verify a published release of the C# MCP SDK. Monitors the Release and Publish Docs workflows triggered by publishing a GitHub release, confirms the packages are listed on NuGet.org, and confirms the versioned documentation site reflects the release. Use when asked to verify a release, check whether a release published correctly, monitor the release or docs workflow, confirm packages on NuGet, or check whether the docs site updated.
|
|
compatibility: Requires gh CLI with repo access for workflow runs and releases, and network access to nuget.org and csharp.sdk.modelcontextprotocol.io.
|
|
---
|
|
|
|
# Verify Release
|
|
|
|
Verify that a published release of `modelcontextprotocol/csharp-sdk` fully shipped. Publishing a
|
|
GitHub release triggers **two workflows in parallel**, and the release is not done until both have
|
|
succeeded and both of their outputs are confirmed live.
|
|
|
|
| Workflow | File | Trigger | Produces |
|
|
|---|---|---|---|
|
|
| Release | [`.github/workflows/release.yml`](../../workflows/release.yml) | `release: published` | NuGet packages published to NuGet.org |
|
|
| Publish Docs | [`.github/workflows/docs.yml`](../../workflows/docs.yml) | `release: published` | The versioned docs site at <https://csharp.sdk.modelcontextprotocol.io> |
|
|
|
|
Use the shared [release branch reference](../shared-resources/release-branches.md) for branch roles
|
|
and release tag conventions.
|
|
|
|
> **Safety: This skill is read-only by default.** It inspects workflow runs, releases, and published
|
|
> artifacts. The only actions it may take are re-running a failed workflow or dispatching a docs
|
|
> refresh, and both require explicit user confirmation.
|
|
|
|
## Process
|
|
|
|
Work through each step sequentially. Present findings at each step and get user confirmation before
|
|
taking any action.
|
|
|
|
### Step 1: Identify the Release
|
|
|
|
The user may provide:
|
|
- **A version or tag** (e.g., `2.0.0-preview.1`, `v1.3.1`) — use directly
|
|
- **No context** — list recent releases with `gh release list --limit 10` and ask the user to select
|
|
|
|
Confirm the release is **published**, not a draft:
|
|
|
|
```
|
|
gh release view {tag} --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,url
|
|
```
|
|
|
|
If the release is still a draft, **stop**. Neither workflow has run — nothing is published, and no
|
|
verification is possible. Tell the user the draft must be published in the GitHub UI first, and
|
|
that publishing is a deliberate human action this skill will not perform.
|
|
|
|
Record the tag, the published timestamp, and the target commitish for the following steps.
|
|
|
|
### Step 2: Locate Both Workflow Runs
|
|
|
|
Find the runs triggered by publishing this release. A release-event run carries the **tag name in
|
|
`headBranch`**, which is an exact identifier — use it rather than correlating on timestamps:
|
|
|
|
```
|
|
gh run list --workflow release.yml --event release --branch v{version} --limit 5 --json databaseId,status,conclusion,headBranch,headSha,createdAt,url
|
|
gh run list --workflow docs.yml --event release --branch v{version} --limit 5 --json databaseId,status,conclusion,headBranch,headSha,createdAt,url
|
|
```
|
|
|
|
**Do not identify runs by "the most recent run" or "created at or after `publishedAt`."** Those
|
|
match any release published in the same window, so a concurrent or closely-following release —
|
|
including a servicing patch published from another branch minutes later — can be reported as this
|
|
release's result, showing a green run for the wrong tag. Confirm `headBranch` equals `v{version}`
|
|
on every run before evaluating it.
|
|
|
|
Cross-check `headSha` against the release's target commitish recorded in Step 1. A mismatch means
|
|
the tag moved between drafting and publishing, and the run validated something other than what was
|
|
reviewed — stop and report it rather than evaluating the run.
|
|
|
|
If more than one run matches the tag, the workflow was re-run; evaluate the **latest attempt** and
|
|
say that earlier attempts existed rather than silently reporting only the newest.
|
|
|
|
Present both runs with their status, conclusion, and URL. Watch them **together** — they run
|
|
concurrently and either can fail independently. Do not report success for the release until both
|
|
are accounted for.
|
|
|
|
If a run cannot be found for either workflow, report which one is missing and check whether the
|
|
workflow is disabled or whether its `if` repository guard excluded the run (both workflows only run
|
|
in the `modelcontextprotocol/csharp-sdk` repository, not in forks).
|
|
|
|
### Step 3: Evaluate the Release Workflow
|
|
|
|
Report the run's conclusion. If it failed, identify the failing job and step and summarize the
|
|
error:
|
|
|
|
```
|
|
gh run view {run-id} --log-failed
|
|
```
|
|
|
|
A failure here does **not** roll back the release — the GitHub release and its tag remain, and the
|
|
workflow is simply re-run once the cause is addressed. Re-running is safe and is usually the right
|
|
first move. Recommend it, but **do not re-run without explicit user confirmation**.
|
|
|
|
> **Never run `dotnet nuget push` and never handle NuGet API keys.** Package publishing happens only
|
|
> through the workflow.
|
|
|
|
### Step 4: Evaluate the Publish Docs Workflow
|
|
|
|
Report the run's conclusion, accounting for these docs-specific behaviors:
|
|
|
|
- **Superseded runs are not failures.** The workflow uses a `pages` concurrency group with
|
|
`cancel-in-progress: true`. Every run rediscovers the current releases and rebuilds the whole site
|
|
from scratch, so a newer run fully supersedes the one it cancels. Report a cancelled run as
|
|
*superseded* and follow the newer run instead.
|
|
- **Version discovery reads published releases.** For each major version >= 1, the workflow takes
|
|
the most recently published non-draft release tagged `v{MAJOR}.*`. A draft release contributes
|
|
nothing.
|
|
- **Every major is rebuilt.** Each major's docs are built from that major's latest release tag into
|
|
its own path (`/v1/`, `/v2/`). A new MAJOR adds a new path; the site root redirects to the newest
|
|
release, prereleases included.
|
|
- **Orchestration comes from `main`.** The scripts and picker assets are always checked out from
|
|
`main`, while each version's content comes from its release tag. A docs fix that lives only in a
|
|
release branch will not affect orchestration.
|
|
|
|
If it failed, summarize the failing step. Common causes are a docs build failure in one version's
|
|
worktree (`make generate-docs`) or a Pages deployment error.
|
|
|
|
### Step 5: Confirm the Published Packages
|
|
|
|
Confirm the exact released version is listed for each shipping package on NuGet.org.
|
|
|
|
Listing can lag a successful workflow run by several minutes. If the workflow succeeded but the
|
|
version is not yet visible, say so explicitly and offer to re-check — **do not report this as a
|
|
failure**. Distinguish "published but not yet indexed" from "not published."
|
|
|
|
Report each package with its status, and flag any shipping package missing from the release.
|
|
|
|
### Step 6: Confirm the Documentation Site
|
|
|
|
Confirm <https://csharp.sdk.modelcontextprotocol.io> reflects this release:
|
|
|
|
1. **Version path** — the major-version path for this release (for example `/v2/`) is live and
|
|
serving the new content.
|
|
2. **Version picker** — the picker offers this release's major version.
|
|
3. **Root redirect** — the site root redirects to the expected default version, which is the newest
|
|
release by publish date, prereleases included.
|
|
4. **Versioning page** — the slugged versioning page for this release,
|
|
`https://csharp.sdk.modelcontextprotocol.io/v{MAJOR}/versioning.html`, resolves. Release notes
|
|
link to it from the Breaking Changes section, and for the first release of a new MAJOR that path
|
|
only comes into existence with this workflow run. Confirm the release notes use the slugged form
|
|
and not the unslugged `/versioning.html`, which tracks the site default and can silently repoint
|
|
when a later MAJOR ships.
|
|
|
|
GitHub Pages caches aggressively, so a short delay after a successful deploy is normal.
|
|
Distinguish "deployed but not yet propagated" from "deployed wrong."
|
|
|
|
### Step 7: Report
|
|
|
|
Summarize the verification as a table covering both workflows and both published outputs, and state
|
|
plainly whether the release is fully verified or what remains outstanding.
|
|
|
|
| Check | Status |
|
|
|---|---|
|
|
| Release workflow | ✅ succeeded — {run URL} |
|
|
| Publish Docs workflow | ✅ succeeded — {run URL} |
|
|
| Packages on NuGet.org | ✅ {version} listed for all N packages |
|
|
| Docs site | ✅ `/v2/` live, picker updated, root redirects |
|
|
|
|
## Remediation
|
|
|
|
Both remediations require explicit user confirmation.
|
|
|
|
**Re-run a failed workflow:**
|
|
|
|
```
|
|
gh run rerun {run-id} --failed
|
|
```
|
|
|
|
**Refresh the docs without a new release** — when documentation content needs correcting after the
|
|
release, the docs workflow accepts a manual dispatch that rebuilds one major version's content from
|
|
an arbitrary ref, without minting a product release:
|
|
|
|
```
|
|
gh workflow run docs.yml --field docs_ref={branch-tag-or-commit}
|
|
```
|
|
|
|
The ref's major version, read from `src/Directory.Build.props`, must have a published release; the
|
|
workflow fails fast if it does not. This replaces only the matching major's HTML — orchestration
|
|
and all other versions are unaffected.
|
|
|
|
## Edge Cases
|
|
|
|
- **Release is still a draft** — stop; neither workflow has run. The user must publish in the GitHub UI.
|
|
- **Docs run cancelled** — expected under the `pages` concurrency group; report as superseded and follow the newer run.
|
|
- **Only one workflow ran** — check whether the other is disabled, or whether the repository guard excluded it (forks do not run either workflow).
|
|
- **Workflow succeeded but NuGet version not listed** — indexing lag; re-check before reporting a failure.
|
|
- **Workflow succeeded but docs not visible** — Pages caching; re-check before reporting a failure.
|
|
- **Docs site missing the new major version** — confirm the release is published and non-draft, then confirm the tag matches `v{MAJOR}.*`.
|
|
- **Root redirects to an unexpected version** — the default is the newest release *by publish date*, including prereleases. A prerelease published after a stable release becomes the default; this is by design.
|
|
- **Release workflow failed after partial publish** — some packages may already be on NuGet.org. NuGet versions cannot be unpublished; re-running skips already-published versions. Report exactly which packages are listed before recommending a re-run.
|
|
- **Versioning link is unslugged or points at the wrong MAJOR** — release notes must link to `/v{MAJOR}/versioning.html` for the released version. Report it so the user can correct the body; the unslugged form tracks the site default and will repoint when a later MAJOR ships.
|
|
- **Verifying an older release** — the docs workflow only ever reflects each major's *latest* release, so an older release's docs path will have been overwritten by a newer one. Verify packages only and note this.
|