GitHub releases and recovery

GitHub releases and recovery

These rules apply to --release (and its --gh-release alias) in all three package scripts, with local or remote sources.

The package version is the tag and release name, and release notes are generated by GitHub. Alpha, beta, RC, and dev versions are marked as prereleases. Archived repositories are rejected, since GitHub does not allow releases on them. For stable, alpha, beta, and RC versions an existing tag or release stops the operation unless --force is explicitly supplied.

A version ending in -dev is a rolling prerelease, including a build on the way to an alpha, beta or RC such as 1.1.0-a2-dev. The first release creates it like any other release. Each later release moves the tag to the new commit, regenerates the release notes, and replaces the ZIP in the same GitHub release, so its URL stays the same. The new ZIP is uploaded under a temporary name and only replaces the old one after the upload is confirmed. The scripts print Updated rolling release: for this path and Published release: for a new release. A dry run shows what would change but never touches the tag, release, or asset. If the tag has to move, the dry-run notes still reflect where the tag points now.

The tag is reserved at the pinned commit before the release is created. A failure after tag creation may leave that tag without a release. The release stays a draft until its asset upload is confirmed. If uploading or publishing fails, the script reports the release URL and exits with an error. Inspect the remote state before retrying. For stable, alpha, beta, and RC versions a retry stops when it finds the existing tag or release unless --force is explicitly supplied. For a -dev version a retry reuses the leftover tag or draft release and finishes the update. A publication timeout may mean publication succeeded but could not be confirmed. Requests have finite timeouts and remote write requests are not retried automatically.

Forced replacement

--force permits replacement of an existing tag, generated notes, and package ZIP. It updates the release in place, preserving its URL and unrelated assets. Stable versions remain stable; prerelease versions remain prereleases. Tag-only and release-without-tag states are handled too.

git-extensions.sh --release --remote --force --dry-run
git-extensions.sh --release --remote --force

This uses the same staging/upload checks as rolling updates. If upload fails, the old ZIP has not yet been deleted. Tag/notes may already have changed, so inspect a failed operation before retrying. --force cannot override GitHub-enforced immutable releases or tag rules. A forced dry run makes no tag/release/asset writes.

Inspect before retrying

Use the repository and version printed by the failed command:

gh release view VERSION --repo OWNER/REPO --json url,isDraft,isPrerelease,tagName,assets
gh api repos/OWNER/REPO/git/ref/tags/VERSION

Replace placeholders; a version containing URL-special characters needs appropriate encoding for an API path. A not-found response differs from an authentication or network failure.

Check the tag target, draft/published state, asset name and asset size. If a stable, alpha, beta or RC tag was reserved but publication failed, a normal retry deliberately stops. Resolve that specific remote state intentionally. Use --force only when replacing that exact version is intended; GitHub-enforced immutable releases cannot be overwritten by this flag. Do not delete a published release merely to bypass platform protections.

For dev releases, a retry can finish a leftover tag/draft or refresh the existing rolling release. Inspect first when a timeout leaves the result uncertain. Generated notes come from GitHub, so preview them for accuracy before publishing.

A dry run is not offline and is not a read-only local operation: it writes the package locally. It makes no GitHub changes. These scripts do not post phpBB forum announcements or merge pull requests.