This guide describes how to create releases for Riksdagsmonitor with full attestations and documentation-as-code.

Document Classification: 🟢 Public
Last Updated: 2026-02-18
Owner: Hack23 AB
Review Cycle: Per release

1. Overview
2. Release Workflow
3. Triggering a Release
4. Release Artifacts
5. Documentation as Code
6. Security & Attestations
7. Deployment
8. Verification
9. Troubleshooting

Riksdagsmonitor follows a comprehensive release process that includes:

• ✅ Automated testing (unit + E2E)
• ✅ Documentation generation (API, coverage, E2E reports)
• ✅ SLSA Build Provenance attestations
• ✅ SBOM (Software Bill of Materials) generation
• ✅ Dual deployment (S3/CloudFront + GitHub Pages)
• ✅ npm package publishing with provenance
• ✅ Automated release notes

The release workflow consists of 3 jobs:

Purpose: Build, test, and generate all documentation

Steps:

1. Set up test environment (Xvfb, Chrome, dependencies)
2. Install npm dependencies
3. Build application with Vite
4. Run unit tests with coverage
5. Run E2E tests with Cypress
6. Clean old documentation
7. Generate API documentation (JSDoc)
8. Generate dependency tree
9. Copy test reports to docs/
10. Create documentation index (docs/index.html)
11. Update sitemap.xml
12. Deploy documentation to GitHub Pages

Duration: ~10-15 minutes

Purpose: Create release artifacts with attestations

Steps:

1. Build production application
2. Create release zip file
3. Generate SHA-256 checksum
4. Generate SBOM (SPDX format)
5. Create build provenance attestation
6. Create SBOM attestation
7. Upload artifacts

Duration: ~5 minutes

Purpose: Create GitHub release, publish npm package, and deploy to production

Steps:

1. Download build and security artifacts
2. Generate release notes with Release Drafter
3. Create GitHub Release with all artifacts
4. Build and publish npm package with provenance
5. Extract build to repository root
6. Deploy to S3/CloudFront with cache headers
7. Invalidate CloudFront cache
8. Display deployment summary

Duration: ~5-10 minutes

Total Workflow Duration: ~20-30 minutes

1. Go to Actions → Release with Attestations → Run workflow
2. Enter version (e.g., v1.0.0)
3. Select prerelease flag (if applicable)
4. Click "Run workflow"

This will:

• Update package.json version
• Create and push a git tag
• Trigger the full release workflow

1. Create and push a version tag:

   git tag v1.0.0
   git push origin v1.0.0

This will automatically trigger the release workflow.

Follow Semantic Versioning:

• Major (v2.0.0): Breaking changes
• Minor (v1.1.0): New features (backward compatible)
• Patch (v1.0.1): Bug fixes (backward compatible)

Each release includes the following artifacts:

• riksdagsmonitor-vX.Y.Z.zip - Production build

  • Minified and optimized for production
  • All HTML, CSS, JS, and assets
  • Ready for deployment

• riksdagsmonitor-vX.Y.Z.zip.sha256 - Checksum

  • SHA-256 hash for integrity verification

• riksdagsmonitor@X.Y.Z - Shared types and utilities

  • Published to npm with provenance attestation
  • TypeScript type definitions for theme, chart, and dashboard types
  • Theme system (dark/light cyberpunk theme, party colors, chart palettes)
  • Chart.js factory and responsive utilities
  • Data loading with fallback, caching, and retry
  • DOM utilities, error boundaries, and fallback UI

  npm install riksdagsmonitor

  import {
    DARK_THEME_COLORS,
    LIGHT_THEME_COLORS,
    getActiveThemeColors,
    getPartyColor,
    CHART_PALETTE,
    BREAKPOINTS,
  } from 'riksdagsmonitor';

• riksdagsmonitor-vX.Y.Z.spdx.json - SBOM

  • Software Bill of Materials in SPDX format
  • Complete dependency inventory
  • License information

• riksdagsmonitor-vX.Y.Z.zip.intoto.jsonl - Build Provenance

  • SLSA Build Provenance attestation
  • Verifiable build metadata
  • Supply chain security

• riksdagsmonitor-vX.Y.Z.spdx.json.intoto.jsonl - SBOM Attestation

  • Attestation for the SBOM
  • Cryptographically signed

All documentation is generated during the release and committed to the docs/ directory:

docs/
├── index.html                    # Documentation hub (landing page)
├── .nojekyll                     # Bypass Jekyll processing
├── api/                          # JSDoc API documentation
│   ├── index.html
│   ├── global.html
│   └── ...
├── coverage/                     # Vitest coverage reports
│   ├── index.html               # Interactive coverage viewer
│   ├── lcov.info
│   └── coverage-final.json
├── test-results/                 # Vitest test results
├── cypress/                      # Cypress E2E test reports
├── dependencies/                 # npm dependency tree
│   ├── dependency-tree.json
│   └── dependency-tree.txt
└── diagrams/                     # Architecture diagrams

• Documentation Hub: https://riksdagsmonitor.com/docs/
• API Documentation: https://riksdagsmonitor.com/docs/api/
• Test Coverage: https://riksdagsmonitor.com/docs/coverage/
• E2E Reports: https://riksdagsmonitor.com/docs/cypress/
• Dependencies: https://riksdagsmonitor.com/docs/dependencies/

Every release includes SLSA Build Provenance attestations that:

• Prove the artifact was built by GitHub Actions
• Include build metadata (commit SHA, workflow, runner)
• Are cryptographically signed and verifiable

Every release includes an SBOM in SPDX format that:

• Lists all dependencies (direct + transitive)
• Includes version information
• Provides license details
• Enables vulnerability tracking

Verify attestations using the GitHub CLI:

# Install GitHub CLI
brew install gh

# Verify build provenance
gh attestation verify riksdagsmonitor-v1.0.0.zip -R Hack23/riksdagsmonitor

# View attestation details
gh attestation view riksdagsmonitor-v1.0.0.zip -R Hack23/riksdagsmonitor

Verify artifact integrity:

# Download artifacts
wget https://github.com/Hack23/riksdagsmonitor/releases/download/v1.0.0/riksdagsmonitor-v1.0.0.zip
wget https://github.com/Hack23/riksdagsmonitor/releases/download/v1.0.0/riksdagsmonitor-v1.0.0.zip.sha256

# Verify checksum
sha256sum -c riksdagsmonitor-v1.0.0.zip.sha256

Every release is deployed to two locations:

• URL: https://riksdagsmonitor.com
• Infrastructure: S3 bucket + CloudFront CDN
• Benefits:
  • Global CDN (low latency worldwide)
  • Custom cache headers (1 hour HTML, 1 year assets)
  • CloudFront edge locations
  • 99.9% SLA

• URL: https://hack23.github.io/riksdagsmonitor (via main branch)
• Infrastructure: GitHub Pages
• Benefits:
  • Free hosting
  • Automatic SSL
  • Version control integration
  • Disaster recovery

Optimized cache headers for performance:

• HTML files: max-age=3600, must-revalidate (1 hour)
• CSS/JS/Images: max-age=31536000, immutable (1 year)
• Metadata (XML/JSON): max-age=86400 (1 day)
• Documentation: max-age=86400 (1 day)

After deployment, CloudFront cache is invalidated (/*) to ensure fresh content.

After a release, verify:

• Release created at https://github.com/Hack23/riksdagsmonitor/releases
• All artifacts uploaded
• Release notes generated
• Attestations available

• Visit https://riksdagsmonitor.com
• Verify application loads
• Check version in footer or version.txt
• Test key functionality

• Visit GitHub Pages URL
• Verify application loads
• Compare with primary deployment

• Visit https://riksdagsmonitor.com/docs/
• Check API documentation
• Review coverage report
• Verify E2E test reports

# Verify build provenance
gh attestation verify riksdagsmonitor-v1.0.0.zip -R Hack23/riksdagsmonitor

# Should output: ✓ Verification succeeded!

Symptom: Prepare job fails during build or tests

Common Causes:

• Test failures (unit or E2E)
• Build errors (Vite)
• Missing dependencies

Solution:

1. Review workflow logs
2. Fix failing tests or build errors
3. Test locally: npm run build && npm test && npm run e2e
4. Re-trigger release

Symptom: Build job fails during attestation generation

Common Causes:

• Missing OIDC permissions
• Artifact not found
• SBOM generation failure

Solution:

1. Verify id-token: write and attestations: write permissions
2. Check artifact was uploaded correctly
3. Review SBOM action logs

Symptom: Release job fails during S3 sync

Common Causes:

• AWS credentials expired
• S3 bucket not accessible
• CloudFront distribution not found

Solution:

1. Verify AWS OIDC role configuration
2. Check S3 bucket exists and is accessible
3. Verify CloudFront distribution ID

Symptom: docs/ directory empty or incomplete

Common Causes:

• JSDoc generation failed
• Coverage report not created
• Test reports missing

Solution:

1. Review prepare job logs
2. Check for errors in documentation generation steps
3. Verify all scripts in package.json are correct

Symptom: Release notes are empty or incorrect

Common Causes:

• .github/release-drafter.yml misconfigured
• Labels missing on PRs
• Release Drafter action failed

Solution:

1. Verify .github/release-drafter.yml exists
2. Check PR labels match release-drafter.yml categories
3. Review Release Drafter action logs

1. ✅ Ensure all tests pass locally
2. ✅ Review CHANGELOG or recent PRs
3. ✅ Update version in package.json (if manual release)
4. ✅ Tag commit with descriptive message
5. ✅ Notify team of upcoming release

1. ✅ Verify deployment on both primary and backup
2. ✅ Test key functionality
3. ✅ Review documentation
4. ✅ Announce release to stakeholders
5. ✅ Monitor for issues

• All GitHub Actions pinned to SHA
• Harden-runner enabled
• OIDC authentication for AWS (no long-lived credentials)
• Least privilege permissions
• Attestations generated and verifiable
• SBOM included
• CodeQL scanning passed
• Dependency scanning passed
• Secret scanning passed

• SLSA Framework
• SPDX Specification
• GitHub Attestations
• Release Drafter
• Semantic Versioning

Maintained by: Hack23 AB
License: Apache License 2.0
Support: https://github.com/Hack23/riksdagsmonitor/issues