| name | github-action-release |
| description | **WORKFLOW SKILL** — End-to-end release process for a GitHub Action repository (e.g., Azure/setup-azd). Covers pre-release smoke testing with `@main`, version bumping across CHANGELOG/README/package.json/package-lock.json, tagging, drafting a GitHub Release, Marketplace publishing, and post-release validation against a consumer repo.
INVOKES: git CLI, gh CLI, npm, ask_user, azd CLI.
USE FOR: release a GitHub Action, cut a new GHA release, publish to GitHub Marketplace, tag new version of setup-azd, draft GitHub release, bump action version, release setup-azd v2.x, post-release verification, run release workflow for an action repo, validate new action version in a consumer repo, fix azd pipeline credentials after release.
DO NOT USE FOR: general code PRs (use pull-request), code review (use code-review), building the action source (use implementation), releasing non-Action Node/npm packages (this skill is specific to GHA Marketplace releases). |
github-action-release
WORKFLOW SKILL — Cut and publish a new version of a GitHub Action, then validate it in a real consumer pipeline.
INVOKES: git CLI, gh CLI, npm, ask_user, azd CLI.
When to use
- Releasing a new version of a GitHub Action repo (e.g.,
Azure/setup-azd) to GitHub Marketplace.
- Any change that requires bumping the action's version tag so downstream workflows (
uses: Org/action@vX.Y.Z) can consume it.
- Post-release validation against a known consumer repo.
Do not use for general PR creation (use pull-request), code review (use code-review), or npm-library releases that are not GitHub Actions.
Workflow
Step 1 — Pre-release smoke test with @main
Before cutting a release, verify main is green end-to-end.
- Confirm all PRs targeting the release are merged into
main and CI on main is green (gh run list --branch main --limit 5).
- In a consumer pipeline, temporarily pin the action to
@main to exercise the un-released code:
- uses: Azure/setup-azd@main
- Trigger the consumer workflow and confirm it succeeds. If it fails, fix forward on
main before proceeding.
Step 2 — Decide the new version
ask_user for the version bump (or infer from the changes):
- Patch (
x.y.Z) — bug fixes, dependency bumps with no behavior change.
- Minor (
x.Y.0) — new features, runtime upgrades (e.g., Node 20 → 24) that keep backward compat for most consumers.
- Major (
X.0.0) — breaking changes (removed inputs, required runner upgrades, etc.).
Step 3 — Update version-bearing files
Open a PR that updates all four files consistently:
-
CHANGELOG.md — add a new section at the top following the existing template. Example (from Azure/setup-azd PR #220):
## 2.3.0 (YYYY-MM-DD)
### Features Added
- [[PR#]](https://github.com/Org/repo/pull/PR#) Short description.
### Breaking Changes
- ...
### Bugs Fixed
- ...
### Other Changes
- ...
Omit sections that have no entries.
-
README.md — update the embedded action.yml snippet (e.g., using: 'nodeNN') and any other code examples that reference implementation details. Do not pin uses: Org/action@vX.Y.Z in the README — by convention the README uses the floating major tag (@v2), which gets moved to the new release in Step 4. Pinning to a full SemVer in README docs would force every downstream copy-paster to re-update on every release.
-
package.json — bump the top-level version field.
-
package-lock.json — bump both version entries (the top-level one and the one under packages."").
-
If the action has a compiled output (e.g., dist/index.js), rebuild and commit:
npm ci
npm run all # or: npm run build && npm run package
The repo's check-dist CI job will fail if dist/ is out of sync.
-
Open the PR via the pull-request skill (do not run gh pr create directly).
Step 4 — Merge and tag
Once the version-bump PR is merged into main:
-
Sync local: git checkout main && git pull origin main.
-
Tags must be signed. Release tags must show the GitHub "Verified" badge — unsigned tags erode consumer trust for a Marketplace action.
-
Create the tag. For Azure/setup-azd, maintain both a full SemVer tag and a floating major tag — this is required because the README and most consumers reference the major tag (@v2), so it must be moved forward on every minor/patch release. Use -s (sign) — never -a — so the tag carries a signature:
git tag -s v2.3.0 -m "Release 2.3.0"
git push origin v2.3.0
# Move the floating major tag so `uses: Org/action@v2` points at the new release
git tag -fs v2 -m "Update v2 to 2.3.0"
git push origin v2 --force
On a major bump, create a new floating tag (v3) instead of moving v2, and open a follow-up PR to update the README samples to @v3. Always ask_user before any --force push.
You may also create the SemVer tag directly in the GitHub Releases UI in Step 5 instead of using git tag, but the floating major tag must still be moved manually via git tag -fs + git push --force.
-
Verify both tags show verified: true on GitHub before drafting the release:
gh api /repos/<owner>/<repo>/git/refs/tags/v2.3.0 |
ConvertFrom-Json | % { gh api "/repos/<owner>/<repo>/git/tags/$($_.object.sha)" } |
ConvertFrom-Json | Select-Object -ExpandProperty verification
If verified is false, delete the tag (git push origin :refs/tags/<tag>), fix signing config, and recreate.
Step 5 — Draft the GitHub Release
- Go to
https://github.com/Org/repo/releases → Draft a new release.
- Tag: select the tag created in Step 4 (or type a new tag name to create it on publish).
- Target:
main.
- Title:
<repo-name>_vX.Y.Z (e.g. setup-azd_v2.3.0). Prefixing the repo name disambiguates from unrelated vX.Y.Z tags in cross-repo release feeds and Marketplace listings.
- Description: paste the CHANGELOG entry for this version. Use "Generate release notes" as a starting point, then trim to match the CHANGELOG.
- Check "Publish this Action to the GitHub Marketplace" and select the primary + secondary categories (match the existing release's categories).
- Leave "Set as the latest release" checked unless this is a back-port.
- Publish release.
Reference: Publishing actions in GitHub Marketplace.
Step 6 — Post-release validation
Run the consumer pipeline twice against the newly published version:
- In the consumer repo, pin the action to the new tag:
- uses: Azure/setup-azd@v2.3.0
- Trigger the workflow (push a dummy commit or use
gh workflow run).
- Watch:
gh run list --repo <custom-test-repo> --limit 3.
- Inspect failures:
gh run view <run-id> --repo <custom-test-repo> --log-failed.
Step 7 — Fix consumer auth if the pipeline fails on Azure login
The most common post-release failure is az login / federated-credential misconfiguration in the consumer repo (not a real regression in the action). Reconfigure with azd:
cd <consumer-repo>
azd pipeline config
azd pipeline config prompts interactively. You must ask_user for each selection — do not guess. Typical prompts:
- CI/CD provider →
GitHub Actions (vs. Azure DevOps).
- Authentication type →
Federated Credential (OIDC) (recommended) vs. Client Credentials (service principal + secret).
- Azure subscription → one of the signed-in subscriptions.
- Azure location / region → e.g.,
eastus2.
- Service principal → create a new one or reuse an existing name.
- Commit & push generated workflow changes? → usually
No unless the user explicitly opts in.
After azd pipeline config succeeds, re-run the consumer workflow and confirm it passes.
Step 8 — Announce / close out
- Verify the release is visible at
https://github.com/marketplace/actions/<action-name> (Marketplace listing can take a few minutes).
- Close the release issue / milestone if one exists.
- Notify the team / post release notes to the usual channel.
Error handling
check-dist CI fails on version PR → dist/ was not rebuilt. Run npm ci && npm run all and amend the PR.git push origin v2 --force refused → branch protection on tags; push via the Releases UI or ask an admin.- Release published but Marketplace listing missing → confirm "Publish to Marketplace" was checked and categories are set; edit the release and re-save.
References
