From 369487074c0fc24dbee0dbbf99a2ce8e170544e2 Mon Sep 17 00:00:00 2001 From: zanejohnson-azure Date: Wed, 3 Jun 2026 15:22:57 -0700 Subject: [PATCH 1/2] feat(skills): add ama-logs-tag-release skill Documents how to create and push the release tag (e.g. 3.4.0) on the merge commit of the release-notes PR, following the lightweight-tag convention used by 3.3.0 and 3.4.0. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/skills/ama-logs-tag-release/SKILL.md | 115 +++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 .github/skills/ama-logs-tag-release/SKILL.md diff --git a/.github/skills/ama-logs-tag-release/SKILL.md b/.github/skills/ama-logs-tag-release/SKILL.md new file mode 100644 index 000000000..0bb5d5395 --- /dev/null +++ b/.github/skills/ama-logs-tag-release/SKILL.md @@ -0,0 +1,115 @@ +--- +name: ama-logs-tag-release +description: "Create and push the git tag (e.g. 3.4.0) for an ama-logs release after its release-notes PR has merged into ci_prod. Use when: 'tag the release', 'cut the 3.X.Y tag', 'create release tag', 'tag ci_prod for release'. DO NOT USE FOR: tagging hotfixes on branches other than ci_prod, creating GitHub Releases with binaries, or signing tags." +argument-hint: "[version] — e.g. '3.4.0'. If omitted, infer from charts/azuremonitor-containerinsights/Chart.yaml." +--- + +# ama-logs Release Tag + +After the release-notes / chart-bump PR (see the `ama-logs-update-charts-release-notes` skill) lands on `ci_prod`, the release is tagged. The tag is what downstream pipelines and the publishing job key off of. + +This skill creates the `` git tag on the merge commit of the release PR and pushes it to `origin`. It mirrors the pattern used by `3.3.0` and `3.4.0`. + +## Required Inputs + +| Input | Description | Example | +|-------|-------------|---------| +| **VERSION** | The release version, no `v` prefix | `3.4.0` | +| **Release PR number** | The merged release PR in `microsoft/Docker-Provider` | `1699` | + +If VERSION was not provided, read it from `charts/azuremonitor-containerinsights/Chart.yaml` (`version:` field). If the release PR number was not provided, find it with: + +```powershell +gh pr list --repo microsoft/Docker-Provider --state merged --base ci_prod ` + --search " Release notes in:title" --json number,title,mergeCommit,state +``` + +## Step-by-step procedure + +### Step 1: Verify the release PR is merged + +```powershell +gh pr view --repo microsoft/Docker-Provider ` + --json state,baseRefName,mergeCommit,mergedAt +``` + +Required values: +- `state` must be `MERGED`. +- `baseRefName` must be `ci_prod`. +- `mergeCommit.oid` will be the SHA we tag. + +If the PR is not merged, **stop** and tell the user — never tag from an un-merged branch. + +### Step 2: Pull the latest tags and confirm the version isn't already tagged + +```powershell +git fetch origin --tags 2>&1 | Select-Object -Last 5 +git tag -l +``` + +If `git tag -l ` outputs anything, the tag already exists. Stop and confirm with the user — do not silently overwrite. + +### Step 3: Confirm the merge commit is reachable from origin/ci_prod + +```powershell +git --no-pager log -1 --oneline +git merge-base --is-ancestor origin/ci_prod; $LASTEXITCODE +``` + +The `log` line should match the release PR title (e.g. `3.4.0 Release notes (#1699)`). `$LASTEXITCODE` must be `0` — meaning the commit is on `ci_prod`. If it isn't, stop. + +### Step 4: Match the prior release's tag style + +Inspect the previous release tag to decide between a lightweight or annotated tag: + +```powershell +git for-each-ref refs/tags/ --format='%(objecttype) -> %(*objectname)%(objectname)' +``` + +- `commit -> ` → lightweight tag (no annotation). +- `tag -> ` → annotated tag. + +The current convention in this repo is **lightweight tags** (e.g. `3.3.0`, `3.4.0`). Stay consistent unless the user explicitly asks for an annotated/signed tag. + +### Step 5: Create the tag + +Lightweight (default — matches existing convention): + +```powershell +git tag +``` + +Annotated (only if the prior release used `tag -> ...`): + +```powershell +git tag -a -m "Release " +``` + +### Step 6: Push the tag + +Push only the new tag — never `git push --tags` from a worktree, which can leak local-only tags. + +```powershell +git push origin refs/tags/ 2>&1 | Select-Object -Last 5 +``` + +Expected output ends with `* [new tag] -> `. + +### Step 7: Verify on origin and report + +```powershell +gh api repos/microsoft/Docker-Provider/git/refs/tags/ --jq '{ref, sha: .object.sha, type: .object.type}' +``` + +`sha` must equal `` (or the annotated-tag object pointing to it). Print to the user: +- Tag name and SHA +- Link: `https://github.com/microsoft/Docker-Provider/releases/tag/` +- Reminder: the build/publish pipeline triggers off this tag — confirm with the release owner before walking away. + +## Important rules + +- **No `v` prefix.** Tags are bare versions: `3.4.0`, not `v3.4.0`. +- **Tag the merge commit of the release PR**, never the PR's head commit on the feature branch and never an arbitrary commit on `ci_prod`. The merge commit is reproducible and is what reviewers approved. +- **Never** force-push or move an existing release tag. If the tag is wrong, talk to the release owner — moving it can break downstream pipelines and consumers who already pulled the prior SHA. +- **Never** create the tag from a stale local `ci_prod`. Always `git fetch origin --tags` first. +- **Never** create a GitHub Release in this skill — publishing/release-notes-on-GitHub is a separate manual step owned by the release manager. From 04a77c85bfbc4112509a695c8bc0296a9e73d743 Mon Sep 17 00:00:00 2001 From: zanejohnson-azure Date: Wed, 3 Jun 2026 15:25:33 -0700 Subject: [PATCH 2/2] fix(skills/tag-release): use annotated tags and add GitHub Release step The documented manual procedure uses `git tag -a` (annotated) and follows up with a GitHub Release draft using auto-generated notes against the previous prod tag. The earlier version of this skill incorrectly defaulted to lightweight tags and stopped after pushing the tag. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/skills/ama-logs-tag-release/SKILL.md | 55 ++++++++++++-------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/.github/skills/ama-logs-tag-release/SKILL.md b/.github/skills/ama-logs-tag-release/SKILL.md index 0bb5d5395..83b2b5175 100644 --- a/.github/skills/ama-logs-tag-release/SKILL.md +++ b/.github/skills/ama-logs-tag-release/SKILL.md @@ -58,36 +58,29 @@ git merge-base --is-ancestor origin/ci_prod; $LASTEXITCODE The `log` line should match the release PR title (e.g. `3.4.0 Release notes (#1699)`). `$LASTEXITCODE` must be `0` — meaning the commit is on `ci_prod`. If it isn't, stop. -### Step 4: Match the prior release's tag style +### Step 4: Identify the previous release tag -Inspect the previous release tag to decide between a lightweight or annotated tag: +You will need the previous release tag for the GitHub Release step (Step 7) — it's what GitHub's "auto-generate release notes" uses as the comparison base. ```powershell -git for-each-ref refs/tags/ --format='%(objecttype) -> %(*objectname)%(objectname)' +git tag -l "3.*" | Sort-Object { [version]$_ } -ErrorAction SilentlyContinue | Select-Object -Last 5 ``` -- `commit -> ` → lightweight tag (no annotation). -- `tag -> ` → annotated tag. +Pick the highest non-`` tag — call it ``. Confirm with the user if there's any ambiguity (e.g. concurrent hotfix branches). -The current convention in this repo is **lightweight tags** (e.g. `3.3.0`, `3.4.0`). Stay consistent unless the user explicitly asks for an annotated/signed tag. +### Step 5: Create the annotated tag -### Step 5: Create the tag - -Lightweight (default — matches existing convention): +The release convention in this repo is **annotated tags** with the version itself as the message (e.g. `3.1.32`, `3.1.34`, `3.4.0` all have message `""`). A few historical tags (`3.1.35`, `3.3.0`) are lightweight — those are regressions, do not match them. ```powershell -git tag +git tag -a -m "" ``` -Annotated (only if the prior release used `tag -> ...`): - -```powershell -git tag -a -m "Release " -``` +`git tag -a` without `-m` opens `$EDITOR`; always pass `-m` so the skill is non-interactive. ### Step 6: Push the tag -Push only the new tag — never `git push --tags` from a worktree, which can leak local-only tags. +Push only the new tag — never `git push --tags` from a worktree, which can leak local-only tags. The form `git push origin tag ` is equivalent. ```powershell git push origin refs/tags/ 2>&1 | Select-Object -Last 5 @@ -95,21 +88,39 @@ git push origin refs/tags/ 2>&1 | Select-Object -Last 5 Expected output ends with `* [new tag] -> `. -### Step 7: Verify on origin and report +### Step 7: Draft and publish the GitHub Release + +The release tag alone does not produce a GitHub Release entry — that is a separate step. Use the GitHub UI (the `gh release create` CLI works too but the UI flow is what the team uses, and "auto-generate release notes" is more reliable from the UI). + +1. Open https://github.com/microsoft/Docker-Provider/releases/new +2. **Choose a tag**: select the `` tag you just pushed. +3. **Previous tag**: change from "auto" to `` (the previous prod tag, from Step 4). +4. Click **Generate release notes**. GitHub will populate the body from PR titles merged between `` and ``. +5. **Release title**: ``. +6. Leave "Set as the latest release" checked. Do NOT mark as pre-release. +7. Click **Publish release**. + +Verify the result: ```powershell gh api repos/microsoft/Docker-Provider/git/refs/tags/ --jq '{ref, sha: .object.sha, type: .object.type}' +gh release view --repo microsoft/Docker-Provider --json tagName,name,isLatest,publishedAt ``` -`sha` must equal `` (or the annotated-tag object pointing to it). Print to the user: -- Tag name and SHA -- Link: `https://github.com/microsoft/Docker-Provider/releases/tag/` +`object.type` must be `tag` (annotated). `isLatest` must be `true`. + +Print to the user: +- Tag name, SHA, and annotation message +- Previous tag used for the diff +- Release URL: `https://github.com/microsoft/Docker-Provider/releases/tag/` - Reminder: the build/publish pipeline triggers off this tag — confirm with the release owner before walking away. ## Important rules +- **Annotated tags only** (`git tag -a -m ""`). Lightweight tags are a regression — the historical `3.3.0` lightweight tag is what we are correcting away from. +- **Tag message = version string**, nothing else (e.g. `-m "3.4.0"`). Matches `3.1.32`/`3.1.34`/`3.4.0`. - **No `v` prefix.** Tags are bare versions: `3.4.0`, not `v3.4.0`. - **Tag the merge commit of the release PR**, never the PR's head commit on the feature branch and never an arbitrary commit on `ci_prod`. The merge commit is reproducible and is what reviewers approved. -- **Never** force-push or move an existing release tag. If the tag is wrong, talk to the release owner — moving it can break downstream pipelines and consumers who already pulled the prior SHA. +- **Never** force-push or move an existing release tag without explicit owner approval. If a tag was created wrong (e.g. lightweight when it should have been annotated), delete-and-recreate is acceptable only **before** downstream pipelines have consumed it — confirm with the release owner first. - **Never** create the tag from a stale local `ci_prod`. Always `git fetch origin --tags` first. -- **Never** create a GitHub Release in this skill — publishing/release-notes-on-GitHub is a separate manual step owned by the release manager. +- **Always** finish with the GitHub Release (Step 7). A pushed tag without a published Release is incomplete — downstream pipelines and consumers expect the Release entry.