Contributing to Workflow Metrics

March 2, 2026 · View on GitHub

Thank you for your interest in contributing. Please read this guide before opening a pull request.

How to contribute

  1. Fork the repository by clicking the "Fork" button on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/<your-username>/workflow-metrics.git
cd workflow-metrics
  3. Create a branch for your change: 
    git checkout -b feat/my-feature
# or
git checkout -b fix/my-bug
  4. Install dependencies and set up the project (see Setup below).
  5. Make your changes, following the coding standards.
  6. Test your changes locally (see Test below).
  7. Commit using Conventional Commits: 
    git commit -m "feat: add DORA metrics export to CSV"
git commit -m "fix: resolve crash when repository has no workflow runs"
  8. Push your branch to your fork: 
    git push origin feat/my-feature
  9. Open a Pull Request against the main branch of this repository. Fill in the PR template that appears automatically.

The CI pipeline will run lint, tests, and a build check on your PR. All checks must pass before the PR can be merged.

Coding standards

  • Use Conventional Commits for commit messages — this drives automated versioning and changelog generation.
  • Write strict TypeScript; avoid any.
  • Keep server-side logic (GitHub API, Supabase, AI calls) in src/lib/server/. Keep UI logic in src/lib/components/ and route files. Do not mix them.
  • Add or update tests for any logic change in src/lib/server/ or src/lib/utils.ts.
  • Maintain coverage thresholds: lines/functions/statements ≥ 80%, branches ≥ 70%.
  • Update README.md if your change adds a feature or modifies existing behaviour.

Prerequisites

  • Node.js >= 24
  • PNPM >= 10
  • A Supabase project (for auth and database)
  • A GitHub OAuth App (for GitHub login)

Setup

pnpm install

Copy the example environment file and fill in your credentials:

cp .env.example .env

Required environment variables:

VariableDescription
PUBLIC_SUPABASE_URLYour Supabase project URL
PUBLIC_SUPABASE_ANON_KEYYour Supabase anon key
GITHUB_APP_IDGitHub App ID (for server-side API calls)
GITHUB_APP_PRIVATE_KEYGitHub App private key
MISTRAL_API_KEYMistral API key (for AI optimization features)

Development

pnpm dev

The app will be available at http://localhost:5173.

Build

pnpm build

Test

pnpm test
pnpm lint
pnpm check

To run tests with coverage:

pnpm test:coverage

Coverage is enforced at: lines/functions/statements ≥ 80%, branches ≥ 70%.

CI (Pull request checks)

On every pull request to main, GitHub Actions runs:

  • Lint: ESLint (TypeScript + Svelte)
  • Test: Vitest with v8 coverage, uploaded to Codecov
  • Build: SvelteKit build check
  • Security: pnpm audit --audit-level=high (fails on high or critical vulnerabilities)
  • Dependency Review: Scans dependency manifest changes for known vulnerabilities

Workflow file: .github/workflows/pull-request.yml.

Security (Harden Runner)

All GitHub Actions workflows use step-security/harden-runner with egress blocking to mitigate supply chain attacks. Only explicitly allowed endpoints can be reached.

What it does:

  • Monitors network egress to detect unauthorized outbound calls
  • Tracks file integrity to detect tampering
  • Monitors process activity for suspicious behavior

Workflows protected:

Audit results and insights are available at the Step Security dashboard.

Release & Publishing

Automated Release

Releases are automated with Semantic Release. On every push to main:

  1. Test job runs: lint, unit tests (Vitest), and build.
  2. Release job runs only if tests pass: Semantic Release analyzes commits, bumps the version, updates package.json and CHANGELOG.md, pushes a release commit, and creates a GitHub release.
  3. Deploy job runs if a new release was created: builds and deploys to Cloudflare Pages.

Use Conventional Commits so versions and changelog are derived from commit messages:

  • feat: ... → minor release (e.g. 1.1.0)
  • fix: ... → patch (e.g. 1.0.1)
  • feat!: ... or fix!: ... → major (e.g. 2.0.0)
  • docs:, chore:, etc. → no release (included in changelog when relevant)

Workflow: .github/workflows/release.yml.

Deployment

Deployment to Cloudflare Pages is triggered automatically after a successful release. The build adapter is @sveltejs/adapter-cloudflare.

Required Secrets (in GitHub repository settings):

SecretDescription
CLOUDFLARE_API_TOKENCloudflare API token with Pages deploy permissions
CLOUDFLARE_ACCOUNT_IDCloudflare account ID
SUPABASE_URLSupabase project URL (production)
SUPABASE_ANON_KEYSupabase anon key (production)
GITHUB_APP_IDGitHub App ID (production)
GITHUB_APP_PRIVATE_KEYGitHub App private key (production)
MISTRAL_API_KEYMistral API key (production)

Stack