Skip to content

v1.0.6 — Add GitHub Pages deployment for benchmark results; release-ready version bump and docs

Choose a tag to compare

View all tags
@tobrien tobrien released this 31 Dec 06:26
· 12 commits to working since this release
v1.0.6
5bb7336
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Summary

This release (1.0.6) prepares the repository for public consumption and makes benchmark results directly viewable via GitHub Pages. The release contains three focused changes: a CI enhancement that publishes benchmark artifacts to GitHub Pages, documentation to explain and support the new automated publishing, and a package version bump that removes the dev pre-release suffix and marks the repo as release-ready.

Contributors: Tim O'Brien (all commits)
Files changed: 5 files changed, ~350 insertions, 3 deletions

Highlights

  • CI: Added a deploy-pages job to the existing benchmark workflow (.github/workflows/benchmark.yml). The job downloads benchmark artifacts, builds a simple pages site (index.html + existing visualizations), uploads the pages artifact, and deploys via actions/deploy-pages@v4. The job runs only on the main branch and depends on the report job.
  • Permissions: The workflow permissions were expanded to include pages: write and id-token: write — these are required by the official GitHub Pages deployment action and OIDC token minting.
  • Docs: Added docs/GITHUB_PAGES_SETUP.md — a detailed guide that explains how to enable Pages, describes what the workflow publishes (visualizations.html, REPORT.md, summary.json), and covers troubleshooting, customization, and security/permission notes.
  • README: Updated README.md to advertise the new automated CI/CD capability and link to the new GitHub Pages setup guide.
  • Package: Bumped package.json from 1.0.5 → 1.0.6 to remove the dev suffix and align package metadata with the release artifacts.

Detailed changes and rationale

  1. CI: deploy-pages job (.github/workflows/benchmark.yml)

  • What changed

    • A new job named deploy-pages was appended to the existing benchmark workflow.
    • The job runs on ubuntu-latest, needs: report, and has an if: github.ref == 'refs/heads/main' guard so it only deploys from main.
    • Steps:
      • Checkout repository (actions/checkout@v4)
      • Download the benchmark artifacts uploaded by the report job (actions/download-artifact@v4) into ./gh-pages.
      • Create a small index.html wrapper that embeds visualizations.html inside an iframe, provides links to REPORT.md and summary.json, and includes simple styling and navigation.
      • Upload the gh-pages directory as a pages artifact (actions/upload-pages-artifact@v3).
      • Deploy to GitHub Pages using actions/deploy-pages@v4. The job exposes the deployment URL via steps.deployment.outputs.page_url and sets the environment url to it.

  • Why

    • Previously benchmark results were produced and attached to GitHub releases and artifacts; this change makes the interactive visualizations immediately viewable in a website-style format and automates public access for stakeholders without downloading artifacts.

  • Implications

    • Users and reviewers can access a hosted interactive dashboard (visualizations.html) and the markdown REPORT.md directly via a GitHub Pages URL.
    • The job only runs on main, which reduces the chance of accidental publication from feature branches or unmerged PRs.
    • The index.html wrapper expects the artifact to contain visualizations.html (the interactive dashboard), REPORT.md, and summary.json — the report job prepares these files before packaging and uploading.
  1. Workflow permissions

  • What changed

    • Added pages: write and id-token: write to the top-level permissions block in the workflow.

  • Why

    • actions/deploy-pages@v4 requires pages: write to create/update Pages deployments, and id-token: write is used for OIDC flows or actions that require token exchange.

  • Implications & notes

    • Repository administrators should verify repository-level Actions permissions (Settings → Actions → General) allow workflows to use the expanded permissions — the workflow-level permission grants are required but the repository settings may still block them.
    • id-token: write enables OIDC token minting; this is standard for modern Actions deployments but should be reviewed by maintainers from a security policy perspective.
  1. Documentation (docs/GITHUB_PAGES_SETUP.md + README.md)

  • What changed

    • Added a new, comprehensive GitHub Pages Setup Guide (docs/GITHUB_PAGES_SETUP.md) explaining: enabling Pages, required workflow permissions, what gets published, job configuration, troubleshooting steps, and customization examples.
    • README.md was updated to advertise the ability to deploy results to GitHub Pages and to link to the setup guide.

  • Why

    • Publishing benchmark results expands the repository's surface area (public site + artifacts). Clear docs reduce friction for maintainers enabling Pages and for consumers expecting stable, discoverable results.

  • Implications

    • The guide instructs maintainers to set Pages Source to "GitHub Actions" and to ensure workflow permissions are set to "Read and write" at the repository level if required.
    • The docs enumerate common failure modes (artifact missing, invalid HTML, permission errors) and direct maintainers where to look in Actions logs.
  1. package.json bump: 1.0.5 → 1.0.6

  • What changed

    • package.json version incremented from 1.0.5 to 1.0.6.
    • Commit message and tag history show prior pre-release/dev tags (v1.0.6-dev.0) — this change removes the pre-release suffix and marks the code as release-ready.

  • Why

    • Aligns published package metadata with the repository state and release artifacts. It signals a stable release, not a development snapshot.

  • Implications

    • No runtime code changes; this is a metadata change. Consumers of any npm package (if package is published) will see a new minor patch version.

Files changed (high-level)

  • .github/workflows/benchmark.yml — +118 lines (added deploy-pages job and new permissions entries)
  • docs/GITHUB_PAGES_SETUP.md — new file (~218 lines) with full setup, troubleshooting, and customization guidance
  • README.md — small additions to point to the new setup guide and to advertise automated Pages deployment
  • package.json — version bump 1.0.5 → 1.0.6
  • package-lock.json — implied updates (commit log indicates lockfile updates were part of the release cadence)

Total changes in this release: ~350 insertions, 3 deletions across 5 files.

Compatibility and breaking changes

  • Breaking changes: None detected.
    • No public API or CLI behavior was altered in this set of commits.
    • The package.json version bump is metadata-only and should not break existing workflows.
  • CI/Permissions: Operational changes that require repository configuration:
    • To allow automated Pages deployment, repository-level Actions permissions must permit workflows to write Pages and mint ID tokens if organization policy restricts those permissions.
    • If the repository or organization disallows the pages: write or id-token: write permissions, the deploy step will fail; maintainers must either adjust settings or limit the workflow.

Security and privacy considerations

  • Publishing benchmark artifacts to GitHub Pages makes report content publicly accessible if the repo is public. Audit the contents of REPORT.md and summary.json to ensure no sensitive data (secrets, environment-specific identifiers, or internal IP addresses) are present before allowing automatic publishing.
  • The workflow grants id-token: write and pages: write at workflow scope. These are required for the official pages deployment flow but should be reviewed by maintainers to confirm they comply with org security policy.
  • The deploy job runs only on main by design; this reduces the risk of accidental exposure from transient branches or forked PRs.

How this release fits the project's evolution

  • Release cadence: The repository has been using short-lived pre-release tags (e.g., v1.0.6-dev.0) and incremental package bumps. This release removes the dev suffix to signal a stable artifact (1.0.6).
  • Feature direction: Prior releases focused on building reliable benchmark generation, result aggregation, and storage as release artifacts. This release extends that pipeline by adding a user-facing presentation layer (GitHub Pages) so that results are easier to consume.
  • Operational maturity: Adding documentation and automation for Pages shows a shift toward making benchmark outputs discoverable and maintaining an operationally repeatable publishing pipeline.

Upgrade / maintainer notes

  • Repository administrators must confirm the following in repository Settings → Actions:
    • Workflow permissions allow the workflow to request pages: write and id-token: write (or select "Read and write permissions" if that is required by org policy).
    • GitHub Pages source is set to "GitHub Actions" (see docs/GITHUB_PAGES_SETUP.md for the step-by-step guide).
  • Verify that the report job produces these files before deploy: visualizations.html, REPORT.md, summary.json. The deploy job relies on these files being present in the uploaded artifact.
  • The report job still creates a GitHub release and uploads the same benchmark tarball; deploy-pages is an orthogonal publishing target (Pages) for immediate web viewing.

Verification checklist (what was changed / what to confirm)

  • The benchmark workflow should still run as before, producing the benchmark-report artifact and a GitHub release.
  • When run on main, the deploy-pages job should:
    • Download the artifact, create index.html (wrapper), upload the pages artifact, and produce a Pages deployment via actions/deploy-pages@v4.
    • Expose the deployment URL at steps.deployment.outputs.page_url and set the environment URL accordingly.
  • The README and new docs/GITHUB_PAGES_SETUP.md should be used to enable Pages and confirm repository-level permissions if the job fails due to permission errors.

Changelog (condensed)

  • feat(ci): add GitHub Pages deployment for benchmark results; update workflow permissions (.github/workflows/benchmark.yml)
  • docs: add GitHub Pages Setup Guide (docs/GITHUB_PAGES_SETUP.md)
  • docs: update README to reference Pages publishing and new docs
  • chore(release): bump package.json version to 1.0.6 (remove dev pre-release suffix)

Closing notes

This release enhances the visibility and accessibility of benchmark results by adding an automated, documented GitHub Pages deployment to the existing benchmark pipeline. There are no breaking API changes; maintainers should review repository Actions permissions and the published report contents before enabling automatic public publishing.

Assets 2
Loading