Add publish-release command to flip draft releases to published (#294)

* Fix invalid env context in release workflow job-level env blocks

The smoke-test and pages-deploy jobs redefined VERSION via
${{ env.VERSION }} in their job-level env: blocks, but the env
context is not available there, failing workflow validation.
The workflow-level env.VERSION is already inherited by all jobs
and steps, so the redundant redefinitions are removed.

https://claude.ai/code/session_014crGVw5Bwiv3nv4EoBimbz

* Publish GitHub release as a final step for immutable releases

The release job created the release already-published and then
uploaded assets, which fails once immutable releases are enforced
(post-publish asset uploads are rejected). Every asset now uploads
to a draft release first; a new `mdsmith-release publish-release`
subcommand flips the fully-populated draft to published as the
final atomic step, but only on the tag-push path. The maintainer's
UI-created draft path is left as a draft for manual publish.

The mise smoke-test is gated to the non-draft path since it
resolves the binary off the public GitHub release, which is not
downloadable while the release is still a draft.

https://claude.ai/code/session_014crGVw5Bwiv3nv4EoBimbz

* test: cover publish-release command and reachable error paths

Add unit tests for runPublishRelease (was 0% covered) and the
PATCH transport / response-body read error branches in
PublishRelease, bringing patch coverage above the Codecov gate.

https://claude.ai/code/session_014crGVw5Bwiv3nv4EoBimbz

* refactor: label publish errors and cover request-build path

Extract newGitHubRequest so the lookup and publish calls share one
request builder, drop the impossible json.Marshal error branch, and
add an Op label to releaseLookupError so a failed publish PATCH no
longer reports as "lookup ... unexpected status" (per review). Adds
white-box tests for the request-build error path; added Go lines in
the PR are now fully covered.

https://claude.ai/code/session_014crGVw5Bwiv3nv4EoBimbz

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jeduden

.github/workflows/release.yml

@@ -363,6 +363,13 @@ jobs:
       id-token: write
       attestations: write
     steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
+        with:
+          go-version-file: go.mod
+          cache: false
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           merge-multiple: true
@@ -412,17 +419,34 @@ jobs:
           cosign sign-blob \
             --bundle checksums.txt.bundle \
             checksums.txt
-      - name: Create release
+      - name: Upload assets to draft release
+        # Always create/update the release as a draft so every asset
+        # uploads while the release is still mutable. With immutable
+        # releases enforced, uploading to an already-published
+        # release is rejected — the publish must be the final step.
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8 # v2.3.2
         with:
-          draft: ${{ needs.trigger-guard.outputs.create_release_is_draft == 'true' }}
+          draft: true
           generate_release_notes: true
           files: |
             mdsmith-*
             checksums.txt
             checksums.txt.bundle
+      - name: Publish release
+        # Path A (tag push): create_release_is_draft == 'false', so
+        # flip the fully-populated draft to published as the final
+        # atomic step — the result is an immutable release. Path B
+        # (maintainer's UI-created draft): create_release_is_draft ==
+        # 'true', so the release is left as a draft for manual
+        # review and publish. Runtime logic lives in mdsmith-release
+        # per docs/development/release-tooling.md.
+        if: needs.trigger-guard.outputs.create_release_is_draft == 'false'
+        env:
+          RELEASE_TAG: ${{ env.VERSION }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: go run ./cmd/mdsmith-release publish-release
 
   smoke-test:
     # Wait until every channel is on the new version before checking
@@ -500,12 +524,19 @@ jobs:
               mdsmith version
     runs-on: ubuntu-latest
     container: ${{ matrix.container }}
-    env:
-      VERSION: ${{ env.VERSION }}
     steps:
+      # The mise channel resolves the binary off the public GitHub
+      # release (ubi backend). On the UI-draft path the release is
+      # left as a draft, so its assets are not publicly downloadable
+      # and mise cannot resolve them — skip mise there. npm/pip are
+      # registry-backed and unaffected by the GitHub release state.
       - name: Install
+        if: &smoke_channel_active >-
+          matrix.channel != 'mise' ||
+          needs.trigger-guard.outputs.create_release_is_draft == 'false'
         run: ${{ matrix.install }}
       - name: Verify version
+        if: *smoke_channel_active
         run: |
           got=$(${{ matrix.run }})
           want="mdsmith ${VERSION}"
@@ -544,11 +575,6 @@ jobs:
       # it expects the binary already on PATH — so no pin lives
       # there.)
       HUGO_VERSION: "0.161.1"
-      # The release tag drives the version Hugo renders in
-      # ``.Site.Params.version`` and the on-disk pin in
-      # website/hugo.toml. Stamp validates that the value has
-      # no leading "v" before rewriting, so strip it here.
-      VERSION: ${{ env.VERSION }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:

cmd/mdsmith-release/main.go

@@ -14,6 +14,7 @@
 //	mdsmith-release sync-docs <src-dir> <dst-dir>
 //	mdsmith-release build-website [--no-fix] [src-dir] [dst-dir]
 //	mdsmith-release check-release-trigger
+//	mdsmith-release publish-release
 //	mdsmith-release check-secret-rotations
 //	mdsmith-release record-rotation <ENTRY_TITLE> <YYYY-MM-DD>
 //
@@ -44,6 +45,7 @@ Commands:
   build-website [--no-fix] [src] [dst]
                                   mdsmith fix (unless --no-fix) + sync-docs.
   check-release-trigger           Emit release trigger guard outputs.
+  publish-release                 Flip the tag's draft release to published.
   check-secret-rotations          Open GitHub issues for secrets due for rotation.
   record-rotation <title> <date>  Update lastRotated in a per-secret rotation file.
 `
@@ -81,6 +83,8 @@ func run(args []string) int {
 		return runBuildWebsite(root, rest)
 	case "check-release-trigger":
 		return runCheckReleaseTrigger(root, rest)
+	case "publish-release":
+		return runPublishRelease(root, rest)
 	case "check-secret-rotations":
 		return runCheckSecretRotations(root, rest)
 	case "record-rotation":

cmd/mdsmith-release/publishrelease.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	flag "github.com/spf13/pflag"
+
+	"github.com/jeduden/mdsmith/internal/release"
+)
+
+func runPublishRelease(_ string, args []string) int {
+	fs := flag.NewFlagSet("publish-release", flag.ContinueOnError)
+	fs.Usage = func() {
+		fmt.Fprintf(os.Stderr, "Usage: mdsmith-release publish-release\n\n"+
+			"Flip the draft GitHub release for the current tag to a\n"+
+			"published release. The `release` job uploads every asset\n"+
+			"to a draft (still mutable); this is the final atomic step\n"+
+			"that publishes it, yielding an immutable release. Reads\n"+
+			"GITHUB_REPOSITORY, RELEASE_TAG, GITHUB_TOKEN, and\n"+
+			"GITHUB_API_URL from the environment. Idempotent.\n")
+	}
+	if err := fs.Parse(args); err != nil {
+		if code := reportFlagParseErr(err, os.Stderr, "mdsmith-release: publish-release"); code >= 0 {
+			return code
+		}
+	}
+	if fs.NArg() != 0 {
+		fs.Usage()
+		return 2
+	}
+
+	return reportError(release.PublishRelease(release.PublishReleaseOptions{
+		Repository: os.Getenv("GITHUB_REPOSITORY"),
+		Tag:        os.Getenv("RELEASE_TAG"),
+		Token:      os.Getenv("GITHUB_TOKEN"),
+		APIBaseURL: os.Getenv("GITHUB_API_URL"),
+	}))
+}

cmd/mdsmith-release/publishrelease_test.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRunPublishReleaseFlipsDraft(t *testing.T) {
+	var patched bool
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPatch {
+			patched = true
+			_, _ = w.Write([]byte(`{"id":42,"draft":false}`))
+			return
+		}
+		_, _ = w.Write([]byte(`{"id":42,"draft":true}`))
+	}))
+	t.Cleanup(srv.Close)
+
+	t.Setenv("GITHUB_REPOSITORY", "jeduden/mdsmith")
+	t.Setenv("RELEASE_TAG", "v1.2.3")
+	t.Setenv("GITHUB_TOKEN", "test-token")
+	t.Setenv("GITHUB_API_URL", srv.URL)
+
+	assert.Equal(t, 0, run([]string{"publish-release"}))
+	assert.True(t, patched)
+}
+
+// TestRunPublishReleaseReportsError covers the reportError branch
+// when PublishRelease fails (here: no token in the environment).
+func TestRunPublishReleaseReportsError(t *testing.T) {
+	t.Setenv("GITHUB_REPOSITORY", "jeduden/mdsmith")
+	t.Setenv("RELEASE_TAG", "v1.2.3")
+	t.Setenv("GITHUB_TOKEN", "")
+
+	assert.Equal(t, 1, run([]string{"publish-release"}))
+}
+
+// TestRunPublishReleaseFlagParseError covers the
+// reportFlagParseErr branch for an unknown flag.
+func TestRunPublishReleaseFlagParseError(t *testing.T) {
+	assert.Equal(t, 2, run([]string{"publish-release", "--bogus"}))
+}
+
+// TestRunPublishReleaseRejectsPositionalArgs covers the
+// fs.NArg() != 0 usage branch.
+func TestRunPublishReleaseRejectsPositionalArgs(t *testing.T) {
+	assert.Equal(t, 2, run([]string{"publish-release", "extra"}))
+}

docs/development/release-tooling.md

@@ -51,6 +51,7 @@ setup step.
 |----------------------------|--------------------------------|
 | `stamp <version>`          | `release.yml` publishing jobs  |
 | `check-release-trigger`    | `release.yml` trigger-guard    |
+| `publish-release`          | `release.yml` release job      |
 | `check`                    | `ci.yml` version-guard         |
 | `build-npm <art> <out>`    | `release.yml` npm job          |
 | `build-wheels <art> <out>` | `release.yml` pypi job         |

docs/development/release.md

@@ -64,11 +64,22 @@ the `create` preflight sees no draft release yet.
 `pull_request_target`, `workflow_run`, and
 `release`. Those triggers can mint OIDC tokens or
 reach the PATs from a non-tag context. The `release`
-event would also still miss draft creation. When
-the run started from `create`, the final GitHub
-Release upload keeps the release in draft state. A
-normal tag push keeps the current
-published-release behavior.
+event would also still miss draft creation.
+
+The `release` job always uploads every asset to a
+**draft** release first. It then publishes the
+release as a separate final step via
+`mdsmith-release publish-release`. Uploading to a
+published release is rejected once immutable
+releases are on. So the publish must be the last
+action.
+
+A normal tag push
+(`create_release_is_draft == 'false'`) auto-publishes
+the full draft. The result is an immutable release.
+A maintainer's UI-created draft
+(`create_release_is_draft == 'true'`) is left as a
+draft for manual review and publish.
 
 `concurrency: { group: release, cancel-in-progress: false }`
 still serializes real releases tag-agnostically.