From SemVer Tags to GitHub Release and Homepage Sync

Release automation looks complex because it contains many steps, but most confusion disappears once you decide where the truth lives. In this course, GitHub Release itself becomes the canonical source for public release state. That sharply reduces the chance that the app repository, docs, and product page all drift apart.

The second key step is to constrain what the homepage repository is allowed to do. It does not create or edit releases on behalf of the source repository. Instead, it reads the published release, transforms it into Astro content, and completes its own build and commit using its own token. That separation is one of the main stability wins in the design.

By freezing the full flow first, every later piece—secrets, generated notes, LLM polishing, dispatch tokens, and import scripts—can be understood in terms of which stage owns it. This chapter is therefore less about tooling and more about drawing the operating boundary map before implementation details.

A common mistake in SemVer automation is treating every `v*` tag as the same kind of release. The course separates stable, beta, and rc explicitly so that prerelease policy and homepage-sync policy do not become ambiguous later.

The second key idea is that a release should not begin life as public. A draft release acts like a staging area. If you only publish after asset upload, generated-note regeneration, optional LLM polishing, and final title/body edits are complete, you avoid exposing half-finished release state to users.

This chapter also includes the recovery path. The default rule is to avoid mutating already-published releases, with manual replay allowed only through `workflow_dispatch` plus an explicit flag. The larger lesson is that automation is not just for convenience; it is also a way to make the default path safer.

Generated notes are the baseline because GitHub already understands the compare range, PR titles, and contributor context inside the release itself. The safe default is therefore to let GitHub produce the first draft and allow the external LLM to act only as a readability layer on top of that.

The course does not use the LLM as a summary engine that invents new facts. Instead, it is treated as a structured post-processor. It can normalize sections such as summary, highlights, fixes, and notes, but only under strict rules: no new claims, exact version retention, and preservation of links and identifiers.

The chapter also asks for an explicit failure policy. If polishing fails, should the release still publish using raw generated notes, or should the whole pipeline stop before publication? That choice is less about prose quality and more about operating philosophy, so the course frames it around how strongly you care about consistency on the public release page.

Users often encounter the product homepage before they ever see the GitHub Release page. That makes it valuable to surface release history on the product site as well. But once the app repository starts committing files directly into the homepage repository, ownership and permissions become tangled very quickly.

The course therefore keeps the source repo limited to triggering the homepage workflow. The homepage repository then fetches the release, generates Astro content, and commits it inside its own workflow. The dispatch token is only used for requesting execution, while the actual content generation and commit rely on the homepage repo’s own `GITHUB_TOKEN`.

The import script is also constrained to published stable releases only. By rejecting draft, prerelease, and unpublished states, the product page avoids leaking internal or incomplete release records. The chapter demonstrates that cross-repo automation is defined as much by what it forbids as by what it enables.

Automation execution is not the same as verification. A green GitHub Actions run does not automatically mean the release body, homepage markdown, and product page all ended up in the expected state. That is why the chapter explicitly defines at least four layers of checks: tag classification, release state, homepage import, and site rendering.

The course treats `gh run watch`, `gh release view`, inspection of the imported markdown file, and no-op reruns as one continuous workflow. The point is to preserve a small but explicit human verification layer. In cross-repo sync, it matters less that “a workflow ran” and more that “exactly the correct stable release was imported.”

The chapter also explains why an ops checklist should survive after the pipeline works. Release automation can feel obvious once it is stable, but many regressions appear when people forget why a specific boundary or replay rule existed in the first place. The checklist acts as a lightweight anti-regression mechanism.