Release Workflow Implementation Summary

February 18, 2026 · View on GitHub

Date: 2026-02-18
Status: ✅ Complete
Pattern: Based on Hack23/blacktrigram release workflow

What Was Implemented

A comprehensive release workflow for the Hack23 homepage static website that implements:

  1. Supply Chain Security (SLSA Build Level 3)
  2. Documentation as Code (automated report generation)
  3. Dual Deployment (GitHub Pages + S3/CloudFront integration)
  4. Automated Versioning (tag-based and manual dispatch)

Files Created

1. .github/workflows/release.yml (546 lines)

Three-job workflow:

  • prepare: Generates documentation

    • HTML validation reports
    • Lighthouse audits (performance, accessibility, SEO)
    • Accessibility compliance (WCAG 2.1 AA)
    • Security report summaries
    • Commits all to docs/ directory

  • build: Creates release artifacts

    • Minifies HTML/CSS/JS
    • Creates ZIP package
    • Generates SBOM (SPDX format)
    • Creates build provenance attestation
    • Creates SBOM attestation

  • release: Publishes and deploys

    • Creates GitHub Release with release-drafter
    • Attaches all artifacts and attestations
    • Deploys to GitHub Pages (backup)
    • Generates deployment summary

2. .github/release-drafter.yml (73 lines)

Automated changelog configuration:

  • Categories: Features, Bug Fixes, Maintenance, Documentation, Security, Accessibility, i18n, Performance
  • Version resolution: major/minor/patch based on labels
  • Template includes quality metrics, security info, deployment details

3. docs/ Directory Structure

Documentation as code storage:

  • index.html - Beautiful documentation viewer with card-based UI
  • README.md - Documentation directory overview
  • WORKFLOW_DOCUMENTATION.md - Complete workflow usage guide
  • Generated files (on release):
    • html-validation.txt
    • lighthouse-*.html and lighthouse-*.json
    • accessibility-report.html
    • security-report.html
    • RELEASE_SUMMARY.md
    • VERSION.txt and version.txt

Key Differences from Black Trigram

AspectBlack TrigramHomepage
Application TypeThree.js game (Vite build)Static HTML/CSS website
Build Processnpm run build with ViteMinify HTML/CSS/JS only
Test SuiteCypress E2E tests, unit testsHTML validation, Lighthouse
API DocsJSDoc generatedN/A (static site)
Dependenciesnpm packages, Three.jsMinimal (images, fonts)
DeploymentGitHub Pages (game)S3/CloudFront + gh-pages backup

Adapted Features

✅ Kept from Black Trigram:

  • Three-job structure (prepare, build, release)
  • SBOM generation with anchore/sbom-action
  • Build provenance attestations
  • SBOM attestations
  • Release-drafter integration
  • Documentation as code principle
  • Security-first approach (harden-runner, minimal permissions)
  • SHA-pinned action versions

✅ Adapted for Static Site:

  • Removed npm build steps (no package.json)
  • Removed test suite (no tests in homepage)
  • Added HTML validation reports
  • Simplified artifact creation (ZIP of HTML/CSS/JS)
  • Integrated with existing main.yml deployment
  • Added Lighthouse audits via treosh/lighthouse-ci-action
  • Created custom documentation reports

Security Implementation

SLSA Build Level 3 Compliance

RequirementImplementation
Build as CodeWorkflow in .github/workflows/release.yml
Provenanceactions/attest-build-provenance@v3.2.0
IsolationGitHub-hosted runners (ephemeral)
ParameterlessDeterministic from git tag
Non-falsifiableGitHub OIDC signing

Permissions Model

# Top-level (default for all jobs)
permissions: read-all

# Job-specific overrides
prepare:
  permissions:
    contents: write  # Commit docs

build:
  permissions:
    contents: read
    id-token: write      # OIDC signing
    attestations: write  # Create attestations

release:
  permissions:
    contents: write   # Create releases
    id-token: write   # OIDC signing

Supply Chain Security Features

  1. Step Security Harden Runner: Network egress auditing
  2. Action Pinning: All actions pinned to commit SHA
  3. SBOM: Complete dependency inventory
  4. Attestations: Cryptographic proof of build
  5. Automated Scanning: Integrated with main.yml ZAP scans

Documentation as Code

Philosophy

All release documentation is:

  • ✅ Generated automatically
  • ✅ Committed to repository
  • ✅ Versioned with code
  • ✅ Available in releases

Reports Generated

  1. HTML Validation (docs/html-validation.txt)

    • Validates all *.html files
    • Uses html-validate npm package
    • Reports errors and warnings

  2. Lighthouse Audits (docs/lighthouse-*.html)

    • Performance metrics
    • Accessibility score (target: 100)
    • Best practices
    • SEO score (target: 100)
    • Generated for key pages

  3. Accessibility Report (docs/accessibility-report.html)

    • WCAG 2.1 AA compliance summary
    • Semantic HTML verification
    • Keyboard navigation status
    • Color contrast compliance

  4. Security Report (docs/security-report.html)

    • Summary of security posture
    • Links to main.yml ZAP scans
    • Security headers status
    • HTTPS enforcement

  5. Release Summary (docs/RELEASE_SUMMARY.md)

    • Version and metadata
    • Documentation checklist
    • Deployment targets
    • Supply chain security info

Testing the Workflow

Pre-release Test

# Create pre-release tag
git tag v1.0.0-rc.1
git push origin v1.0.0-rc.1

Production Release

# Create production tag
git tag v1.0.0
git push origin v1.0.0

Manual Dispatch

  1. Go to Actions → Build, Attest and Release
  2. Click "Run workflow"
  3. Enter version (e.g., v1.0.0)
  4. Select pre-release option if needed
  5. Run

Integration with Existing Workflows

main.yml (Existing)

  • Triggers on: push to master
  • Actions:
    • Minifies HTML/CSS/JS
    • Deploys to S3/CloudFront
    • Runs Lighthouse audits
    • Performs ZAP security scans

release.yml (New)

  • Triggers on: tags v* or manual
  • Actions:
    • Generates documentation
    • Creates versioned release
    • Produces SBOM and attestations
    • Deploys to GitHub Pages

Workflow: Push to master → main.yml deploys. Create tag → release.yml releases.

Verification Commands

Verify Attestations

gh attestation verify homepage-v1.0.0.zip --owner Hack23

View SBOM

gh release download v1.0.0 -R Hack23/homepage -p "*.spdx.json"
cat homepage-v1.0.0.spdx.json | jq

Check Documentation

git clone https://github.com/Hack23/homepage
cd homepage
ls -la docs/

Success Criteria

  • Workflow follows Black Trigram pattern
  • SLSA Build Level 3 attestations generated
  • SBOM in SPDX format created
  • Documentation committed to repository
  • Dual deployment (gh-pages + note for S3)
  • Security-first approach implemented
  • Release-drafter configured
  • Comprehensive documentation provided
  • Zero security vulnerabilities (CodeQL passed)

Next Steps

  1. Test the workflow by creating a test tag
  2. Verify attestations are correctly generated
  3. Review generated documentation in docs/
  4. Validate deployment to GitHub Pages
  5. Create first production release (v1.0.0)

References

Implementation Status: ✅ Complete and ready for testing
Security Status: ✅ CodeQL passed with zero alerts
Documentation Status: ✅ Comprehensive documentation provided