Skip to content

RELEASING.md

Latest commit

 

History

History
122 lines (91 loc) · 5.59 KB

RELEASING.md

File metadata and controls

122 lines (91 loc) · 5.59 KB
Raw

GitHub-only tag-free releases

Teflon releases are published from a specific commit on main without creating or consulting a Git tag. GitHub provides the approval gate, durable archive history, provenance attestations, and public HTTPS delivery. No AWS account, cloud role, storage bucket, CDN, OpenPGP key, release variable, or release secret is required.

Publication model

The Publish tag-free release workflow performs three jobs:

  1. build captures the dispatched main head, proves that it belongs to main, validates the POM version and release notes, runs the Maven build and tests, generates a CycloneDX SBOM, and uploads a seven-day candidate artifact.
  2. publish waits for approval through the release environment. It obtains the repository's public Pages URL, creates the release manifest and checksums, generates GitHub artifact attestations, and commits the release to the automatically managed release-archive branch.
  3. deploy publishes the complete archive through GitHub Pages using GitHub's official Pages actions.

The workflow never reads, creates, or pushes a Git tag. It uses only the run-scoped GITHUB_TOKEN and OIDC token that GitHub creates automatically.

The archive contains:

release-archive:/
  releases/1.4.0/
    teflon-1.4.0-jar-with-dependencies.jar
    sbom.json
    RELEASE_NOTES.md
    SHA256SUMS
    release.json
  channels/
    candidate.json
    stable.json
  index.json

Version directories are immutable. Publication refuses to replace a version when its source commit, artifact digests, sizes, or public URLs differ. An interrupted deployment can safely be retried: an identical version already stored in the archive is reused, even though the retry has a different workflow run ID and timestamp. Git history on release-archive provides an additional recovery trail for channel and index changes.

One-time GitHub configuration

  1. Open Settings > Pages in the GitHub repository.
  2. Under Build and deployment, set Source to GitHub Actions.
  3. Keep the existing release environment restricted to protected branches with the repository owner as a required reviewer. Do not add variables or secrets.
  4. GitHub creates the github-pages environment on the first deployment. Restrict it to main if GitHub does not apply that policy automatically.

The workflows request their exact permissions in YAML. The repository-wide default workflow permission can remain read-only.

GitHub Pages normally serves this repository at:

https://maxdeliso.github.io/teflon

The workflow reads the actual base URL from GitHub, so a Pages custom domain works without a workflow variable. Set up a desired custom domain before the first publication because the public base URL is recorded in each immutable release manifest.

The release-archive branch is created automatically during the first publication. Do not create it, edit it, merge it into main, or use it for application development.

Preparing a release

  1. Set a unique, non-SNAPSHOT version in pom.xml.
  2. Add complete notes at release-notes/<version>.md.
  3. Merge the change through the normal pull-request workflow and wait for CI on main to pass.
  4. Dispatch Publish tag-free release from main. It captures the current main head and publishes only to the candidate channel; there is no SHA or channel to enter.
  5. Review the completed build job, then approve the release environment deployment.
  6. Verify the Pages manifest, SHA-256 digests, SBOM, application behavior, and GitHub provenance attestation.
  7. Dispatch Promote tag-free release with its version field blank. It reads the candidate version and promotes it to stable. Approve the release environment again. Promotion verifies every stored file and changes only the channel pointer; it does not rebuild the application.

Starting a release

Using the GitHub CLI:

gh workflow run release.yml --ref main
gh workflow run promote-release.yml --ref main

No git tag, tag push, GitHub Release, cloud credential, or signing-key command is part of this process.

Verification

Download the executable JAR and compare its SHA-256 digest with release.json or SHA256SUMS. Verify GitHub's provenance attestation with:

gh attestation verify <path-to-jar> --repo maxdeliso/teflon

The attestation connects the artifact digest to this repository, the release workflow, its source commit, and its GitHub-hosted build. The manifest also records the source SHA and the originating workflow run.

GitHub Pages may briefly cache a mutable channel pointer. During release verification, append a unique query string such as ?run=<workflow-run-id> when fetching candidate.json or stable.json. Versioned release URLs are immutable and do not need cache busting.

Promotion and rollback

Published version directories are never changed or removed. Roll back by running Promote tag-free release and entering a previously verified tag-free version in its optional version field. Never replace files beneath releases/<version>/.

Legacy tag-based releases remain available and unchanged, but cannot be targeted by the new promotion workflow because they do not have a manifest in release-archive. Until a second tag-free version exists, retain the legacy GitHub release as the fallback for the first GitHub Pages publication.

Capacity

GitHub Pages is appropriate for the project's current release size. GitHub documents a 1 GB published-site limit and a soft 100 GB monthly bandwidth limit. Check the archive size as releases accumulate; move to dedicated artifact hosting before approaching either limit.