---
name: release
description: Use when shipping a new dotnet-inspect version; coordinate certification, NuGet and GitHub publication, and matching production and CoreCLR site deployments.
---

# Release dotnet-inspect

Use this maintainer skill when the user asks to ship, publish, or release a new
dotnet-inspect version. Read
[`docs/release-workflow.md`](../../../docs/release-workflow.md) first; it owns
the release contract and failure handling. This skill is an operator playbook,
not a substitute for that document or the workflows.

A release is one exact `(commit SHA, VersionPrefix)` pair shared by the NuGet
packages, GitHub release, `https://dotnet-inspect.net`, and the CoreCLR
comparison site. Never advance only the packages or only one site.

## Prepare release notes and hand off intake

Read the current release tracker from `AGENTS.md`. It is a candidate ledger, not
a release manifest; the exact shipped SHA decides which changes shipped.
The release agent owns reconciliation of every release-managed central file
defined in `AGENTS.md`; tracker suggestions are its release-preparation input.

Before selecting the outgoing release commit:

1. Create the successor release tracker with the same intake instructions:
   comments briefly describe user-observable changes and link their implementing
   PR or stack before the implementation merges.
2. Update `AGENTS.md` to name and link the successor's actual issue number.
   Ordinary change PRs now report there instead of editing
   `src/DotnetInspect.Cli/release-notes.md`.
3. Reconcile every release-managed central file defined in `AGENTS.md` from
   tracker suggestions whose implementing changes are ancestors of the proposed
   release commit. Comment when current content already covers a suggestion or
   it no longer applies.
4. Write the outgoing release notes from the candidate comments and linked
   implementations on both the outgoing and successor trackers. Include only
   implementations after the previous release commit that are ancestors of the
   proposed release commit. Issue placement never determines membership; the
   pre-merge comment requirement makes that intake complete.
5. Land the release-preparation change, including all central-file
   reconciliation, and select that commit as the exact release SHA. Later
   merges are outside its history. Immediately before dispatch, recheck both
   trackers against that SHA. If a late comment exposes a qualifying
   release-note candidate or central-file suggestion, or the history and
   prepared artifacts otherwise disagree, correct the notes or central file as
   applicable and select the replacement commit.

After packages, the GitHub release, production, and CoreCLR all succeed, comment
on the successor tracker with the released version, release URL, and full
shipped SHA. State that changes at or before that commit shipped in the
completed release and later changes remain candidates for the successor.
Before closing the outgoing tracker, copy or link every still-eligible entry
whose implementation is not an ancestor of the shipped SHA to the successor;
preserve the original entry. Listing successor entries that actually shipped
in the completed release is optional. A retry retains the same trackers and
must not claim success early.

## Collect the release evidence

From `main`, collect:

1. The successful `ci.yml` main-push run ID that selects the release commit.
2. The most recent completed, non-cancelled Deep Inspect `test` run at or before
   that commit, including every required job conclusion.
3. The successful `deploy-inspect-web.yml` run ID for the exact release commit.
   Use the main-push run by default. An operator-dispatched main staging run
   requires explicit authorization during promotion.

Compare the full CI and staging SHAs before dispatching:

```bash
set -euo pipefail
: "${ci_run_id:?set ci_run_id to the successful main CI run ID}"
: "${staging_run_id:?set staging_run_id to the matching staging run ID}"

ci_sha=$(gh run view "$ci_run_id" --json headSha --jq .headSha)
site_sha=$(gh run view "$staging_run_id" --json headSha --jq .headSha)

[[ "$ci_sha" =~ ^[0-9a-f]{40}$ ]] || {
  printf 'invalid CI SHA: %s\n' "$ci_sha" >&2
  exit 1
}
[[ "$site_sha" =~ ^[0-9a-f]{40}$ ]] || {
  printf 'invalid staging SHA: %s\n' "$site_sha" >&2
  exit 1
}
if [ "$ci_sha" != "$site_sha" ]; then
  printf 'release SHA mismatch: CI=%s staging=%s\n' \
    "$ci_sha" "$site_sha" >&2
  exit 1
fi

printf 'release SHA: %s\n' "$ci_sha"
```

Green evidence at the exact target leaves both evidence overrides disabled.
When the selected Deep Inspect workflow or a required job is non-successful, a
person may set `accept_failed_certification` only after reviewing every
disclosed conclusion and accepting those known gaps. This preserves the red
result as evidence rather than relabeling it successful.

A person may independently set `allow_later_commit` after reviewing the changes
between the observed commit and a later `main` target. Neither override relaxes
site identity: select a staging run for that same exact target SHA. If that
staging run was operator-dispatched, the person must also set
`allow_manual_staging`. All overrides are release-specific, not standing
authorization.

The SHA comparison is the last dependable veto before dispatch. The `nuget`
environment has no approval gate; package publication proceeds automatically
after its builds.

Confirm that the release commit contains the intended `VersionPrefix`, release
notes, package `README.md`, and embedded product skills. Record the documentation
checkpoint even when no edits were required.

When reconciling the shipped skill corpus (`skills/*/SKILL.md`, embedded in the
tool binary and registered in `SkillCommand.Skills`), check scope as well as
accuracy: each shipped skill must describe a genuine end-user capability of the
published tool, not a repository-internal process, CI/certification harness, or
maintainer workflow (that content belongs under `.github/skills/` instead, and
is never embedded or registered). Adding a new skill to the shipped corpus, or
moving a skill into or out of it, is a product-surface change and needs the
repository owner's explicit approval before landing — do not add or relocate a
shipped skill unilaterally while doing routine release reconciliation.

Reconcile the bootstrap skill in the peer `richlander/dotnet-skills` repository
against the release's `VersionPrefix` and generated `dotnet-inspect skill list`.
Keep it at or below 60 lines: explain the basic command UX and advertise every
embedded focused skill, while deferring detailed guidance to the version-matched
tool. When content or version changes, set every peer skill and plugin manifest
version to the release version and publish that repository's update. If the
peer repository is already current and no files change, do not make a no-op
peer release.

## Publish package and site together

Open `release.yml` and `promote-inspect-web.yml` together:

1. Dispatch `release.yml` with the CI run ID, certification run ID, the intended
   `accept_failed_certification` and `allow_later_commit` values, and
   `confirm=publish`.
2. Dispatch `promote-inspect-web.yml` with the matching staging run ID and
   `confirm=promote`. Leave `allow_manual_staging=false` for a push run; set it
   only with explicit authorization for an operator-dispatched staging run.
3. Confirm immediately that both resolve jobs report the same full release SHA.
   If either is wrong, cancel both workflow runs before package publication
   starts. Do not leave a stale promotion run waiting for approval.
4. Monitor the package builds and automatic NuGet publication.
5. Wait for the package workflow and GitHub release to succeed, then approve
   the production-site environment. Never promote the site first.

Do not substitute a newer run after the SHA comparison. Production promotion
automatically invokes the CoreCLR deployment with the resolved SHA, staging run
ID, and artifact ID. The release is complete only when both top-level workflows
and the nested CoreCLR deployment succeed.

## Verify and recover

Verify the package version and commit in NuGet and the GitHub release. Then
check the production and CoreCLR sites' data bars for the same version and
linked commit.

If the package workflow fails, leave site production unapproved and retry with
the same CI and Deep Inspect run IDs and the same explicit acceptance values.
Package retries tolerate
already-published artifacts with `--skip-duplicate`. If site promotion fails
after package publication, retry with the same staging run ID; site retries
revalidate and promote the same staged artifact. A different SHA, ancestry-only
relationship, or matching version string is not a valid substitute.

If the CoreCLR deployment fails after production promotion, rerun the failed
jobs in that promotion run. Do not dispatch a new promotion or substitute a
newer staging run; the nested deployment retains the exact promoted identity.

If a newer `main` push cancels the release commit's staging run, wait for active
staging work to finish and rerun the original push-triggered run:

```bash
gh run rerun "$staging_run_id" --failed
```

Rerun only failed or cancelled jobs so a successful build keeps its artifact
while deployment retries. If GitHub reruns a cancelled build after upload, the
workflow replaces the retained same-name artifact;
`PromotionWorkflowContract` gates that promotion still sees exactly one.
Promote the successful failed-job rerun. Do not substitute a manual staging
dispatch by default. If exceptional circumstances require one, obtain explicit
authorization, confirm its SHA still equals the package target, and enable
`allow_manual_staging` during promotion.