--- name: ai-assist-git-publish description: "Publish a GitHub Release when CHANGELOG.md's top version is ahead of the latest published release. Only invoke when the user explicitly types /ai-assist-git-publish. Never auto-trigger from general conversation about releases, tags, or versions." ---

# Git Publish

Publish a GitHub Release for the current repository whenever `CHANGELOG.md`'s top version is ahead of the latest release published on GitHub. This closes the loop after a version bump lands on the default branch — `ai-assist-changelog-bump` computes and merges the version number, this skill turns that merged CHANGELOG entry into an actual GitHub Release.

This skill is only invoked manually by the user — never auto-trigger.

**Prerequisites:** GitHub CLI (`gh`) installed and authenticated, and a git repo with a GitHub remote and a `CHANGELOG.md` at the repo root.

## Workflow

### Step 1 — Preflight

Run `git status --porcelain`. If the output is non-empty, stop immediately — do not switch branches or take any other action. Tell the user:

> Working tree has uncommitted changes. Commit or stash them, then re-run this skill.

Identify the repository and its default branch (never hardcode either — this skill runs in any repo):

```bash gh repo view --json nameWithOwner,defaultBranchRef -q '.nameWithOwner + " " + .defaultBranchRef.name' ```

Store these as `$REPO` and `$DEFAULT_BRANCH`. If this command fails, the repo has no GitHub remote or `gh` isn't authenticated — report the error verbatim and stop.

If the current branch is not `$DEFAULT_BRANCH`, ask the user before switching:

> Currently on `<branch>`, but releases are published from `$DEFAULT_BRANCH`. Switch to `$DEFAULT_BRANCH` and pull latest? (yes / no)

On "no", stop. On "yes" (or if already on `$DEFAULT_BRANCH`), sync with the remote. Run these as two separate, non-chained commands — never `&&`/`;`-chain `git`/`gh` commands, since PowerShell pre-7 rejects `&&`:

```bash git checkout $DEFAULT_BRANCH git pull origin $DEFAULT_BRANCH ```

### Step 2 — Read CHANGELOG.md

Read `CHANGELOG.md` at the repo root. If it doesn't exist, tell the user and stop.

Parse the first version heading as `$CHANGELOG_VERSION`. CHANGELOGs use different heading conventions — all of these are valid and must be handled:

| Style | Example | |-------|---------| | Bracketed (Keep a Changelog) | `## [1.8.1] - 2026-08-13` | | `v`-prefixed | `## v1.8.1 - 2026-08-13` | | Bracketed + `v` | `## [v1.8.1] - 2026-08-13` | | Bare | `## 1.8.1` |

Alternate date separators (`–`, `—`, `(2026-08-13)`) and a missing date also count as matches. A tolerant pattern:

```bash grep -m1 -E '^##[[:space:]]+\[?v?[0-9]+\.[0-9]+\.[0-9]+\]?' CHANGELOG.md ```

Strip any surrounding `[`/`]` and any leading `v` — `$CHANGELOG_VERSION` is always bare semver (`1.8.1`).

Skip `## [Unreleased]` / `## Unreleased` headings — they are not concrete versions. If the top concrete heading is preceded only by an Unreleased section, that's fine; use the first real version. If there is **no** concrete version heading at all, tell the user there's nothing to publish and stop.

Capture the section body — everything from immediately after that heading up to (but not including) the next `##` version heading, or end-of-file if there is no next heading — as `$NOTES_BODY`.

### Step 3 — Determine the latest published release

```bash gh release view --repo $REPO --json tagName -q .tagName ```

**There is no `latest` argument.** Bare `gh release view` (with no tag) already means "the latest release" — passing the literal word `latest` is treated as a tag name and fails with `release not found`.

Record the raw tag as `$LATEST_TAG` (used in Step 6 to match the repo's existing tag style), then strip any leading `v` to get `$RELEASE_VERSION`. If the command exits non-zero for **any** reason (no releases yet, transient error, etc.), set `$RELEASE_VERSION = "0.0.0"` and `$LATEST_TAG = ""` — no error-text matching is needed since the outcome is the same either way.

### Step 4 — Compare versions

Compare `$CHANGELOG_VERSION` vs `$RELEASE_VERSION` as a numeric `(major, minor, patch)` tuple. Never do a plain string/lexicographic compare — e.g. `"1.9.0" > "1.10.0"` is true as strings but wrong numerically.

### Step 5 — Not ahead: no-op

If `$CHANGELOG_VERSION` ≤ `$RELEASE_VERSION`, print a simple status message showing both versions and stop:

> CHANGELOG top version ($CHANGELOG_VERSION) is not ahead of the latest published release ($RELEASE_VERSION). Nothing to publish.

No error is raised and no release is created.

### Step 6 — Ahead: compute and confirm

If `$CHANGELOG_VERSION` > `$RELEASE_VERSION`, compute:

- `tag` — match the repo's existing tag style. If `$LATEST_TAG` starts with `v`, use `"v$CHANGELOG_VERSION"`; if it's a bare semver, use `"$CHANGELOG_VERSION"`. If there are no prior releases (`$LATEST_TAG` is empty), check existing git tags with `git tag --list --sort=-v:refname | head -5` and follow their style; default to `"v$CHANGELOG_VERSION"` when there's nothing to infer from. - `title = "$CHANGELOG_VERSION"` - `notes = "# What's New 🎉\n\n$NOTES_BODY"`

Present all of it to the user and wait for an explicit yes/no answer before any write happens:

> 🚀 [Publish Release — $REPO] > > CHANGELOG is ahead of the latest published release: > - **Current release:** $RELEASE_VERSION > - **CHANGELOG top version:** $CHANGELOG_VERSION > > Proposed release: > - **Tag:** $tag > - **Title:** $title > - **Target:** $DEFAULT_BRANCH > - **Notes:** > ``` > $notes > ``` > > Publish this release? (yes / no)

### Step 7 — Publish (on approval)

On "yes", write `$notes` to a temp file — never pass multiline text inline via `--notes`, that regresses into a quoting bug — then create the release targeting the default branch:

**bash:**

```bash NOTES_FILE=$(mktemp) printf '%s' "$notes" > "$NOTES_FILE" gh release create "$tag" --repo "$REPO" --title "$title" --notes-file "$NOTES_FILE" --target "$DEFAULT_BRANCH" rm -f "$NOTES_FILE" ```

**PowerShell:**

```powershell $NotesFile = [System.IO.Path]::GetTempFileName() Set-Content -Path $NotesFile -Value $notes gh release create "$tag" --repo "$Repo" --title "$title" --notes-file "$NotesFile" --target "$DefaultBranch" Remove-Item -Path $NotesFile ```

Always delete the temp file afterward, regardless of whether the `gh release create` command succeeded or failed.

**Failure handling — already-exists classification:** if `gh release create` exits non-zero, inspect the error text.

- If and only if it contains the substring `already exists` (real output: `HTTP 422: Validation Failed` / `Release.tag_name already exists`), report this to the user as already published, not as a raw CLI error:

> This version ($CHANGELOG_VERSION) was already published as a release — nothing more to do.

- Every other failure (auth, network, permissions, etc.) must be surfaced to the user verbatim. Never silently reclassify a genuine failure as "already published."

### Step 8 — Verify

Confirm the release now exists and report its URL:

```bash gh release view "$tag" --repo "$REPO" ```

Report the release URL to the user.

## Rules

- Only run when the user explicitly invokes `/ai-assist-git-publish` — never auto-trigger - Never modify `CHANGELOG.md`, `package.json`, or any other file — this skill only reads them - Never run a local `git tag` or `git push` — tag creation is delegated entirely to `gh release create --target $DEFAULT_BRANCH` - Never hardcode the repository or the default branch — always derive both from `gh repo view` - Never switch branches without asking, and never proceed with a dirty working tree - Match the repo's existing tag style (`v1.2.3` vs `1.2.3`) rather than assuming a `v` prefix - Support all common CHANGELOG heading styles (`## [x.y.z]`, `## vx.y.z`, `## [vx.y.z]`, `## x.y.z`) and always compare bare semver numerically, never as strings - Always use `--notes-file`, never inline multiline `--notes` - Always clean up the temp notes file, even on a mid-run error - Always get explicit user approval before any write (Step 6) — no release is created without a yes - On a latest-release lookup failure (Step 3), treat it as "no prior release" (baseline `0.0.0`) — no error-text matching needed - On a `gh release create` failure (Step 7), only reclassify as already-published when the error contains `already exists` — every other failure must be shown verbatim, never swallowed - This skill is idempotent and safe to re-run at any time — re-running after a successful publish hits the Step 5 no-op, and re-running after a race-lost publish hits the Step 7 already-exists handling