heartbeat

Static activity dashboard for projects explored at Sovereign Engineering cohorts. It renders commits, PRs, issues, and releases as a compact git log --oneline style timeline.

Target site: heartbeat.sovereignengineering.io

Data is fetched at build time. The browser only reads public/data/events.json, so visitors never call GitHub directly and never spend API rate limit.

Fork provenance: this project is adapted from OpenSats/heartbeat. Keep the upstream remote pointed at OpenSats for later generic fix PRs.

Develop

Requires Bun 1.3+.

bun install
export GITHUB_TOKEN=ghp_yourtoken   # public_repo scope is enough for public repos
bun run fetch                       # writes public/data/events.json
bun run dev

Useful checks:

bun test
bun run typecheck
bun run lint
bun run format:check
bun run build

Configure

Heartbeat derives its repo set from the Sovereign Engineering website project catalog.

Default source:

• https://raw.githubusercontent.com/soveng/website/main/src/data/showcaseProjects.json

Rules:

• GitHub repo URLs become owner/repo.
• GitHub URLs with deeper paths, such as /pull/123 or /tree/main, still map to the base repo.
• GitHub owner/org URLs, such as github.com/orgs/Routstr, expand to all public non-archived repos for that owner.
• Public github.com/soveng repos are always added to the soveng group.
• Non-GitHub and site-only project links are reported and skipped.

Override source for local testing:

SOVENG_PROJECTS_JSON=/path/to/showcaseProjects.json bun run import:repos
SOVENG_PROJECTS_JSON=https://example.com/showcaseProjects.json bun run fetch

Knobs for the activity window and per-repo page sizes live at the top of scripts/fetch.ts.

Branch workflow

• master is the Sovereign Engineering heartbeat base.
• upstream/master tracks OpenSats heartbeat and is not used as the fork base.
• Create scoped issue branches from latest master, named issue/NN-short-name.
• Merge issue branches back to master with git merge --ff-only.
• Keep issue branches after merge so they remain available for review and later upstream extraction.
• For upstream PRs, create new branches from upstream/master and manually port only generic fixes. Do not include Sovereign Engineering branding, catalog logic, domain config, or Bun-only choices unless upstream asks for them.

Deploy

Cloudflare Pages is the canonical hosted deployment path for this fork.

Built with Bun. Deployment builds must run the GitHub fetcher before vite build because public/data/events.json is generated and intentionally ignored by git. The browser only reads the generated file from the published dist output.

Local env:

• GITHUB_TOKEN or GH_TOKEN: GitHub token used locally by the fetcher for owner expansion and GraphQL activity fetches.
• SOVENG_PROJECTS_JSON: optional explicit project catalog path or URL.
• HOSTED_BASE_URL: optional base URL for bun run hosted:smoke.

Cloudflare Pages env:

• GITHUB_TOKEN: read-only GitHub token used by bun run fetch.
• SOVENG_PROJECTS_JSON: optional explicit project catalog path or URL.
• BUN_VERSION: 1.3.3.
• SKIP_DEPENDENCY_INSTALL: 1.

GitHub Actions repo secrets:

• CLOUDFLARE_PAGES_DEPLOY_HOOK_URL: Cloudflare Pages deploy hook URL configured for the master branch.

Cloudflare Pages

Create a Cloudflare Pages project linked to soveng/heartbeat:

• Production branch: master

• Framework preset: React (Vite). If only React is offered, choose React. Do not choose a server-side framework preset.

• Build command:

  bun install --frozen-lockfile && bun run deploy-build

• Output directory: dist

• Root directory: repository root

Scheduled refreshes are handled by .github/workflows/refresh.yml. The workflow uses a Cloudflare Pages deploy hook every 6 hours to rebuild master. Store the hook URL in the GitHub Actions secret named CLOUDFLARE_PAGES_DEPLOY_HOOK_URL.

Verification commands:

HOSTED_BASE_URL=https://<cloudflare-pages-domain> bun run hosted:smoke --strict-headers
HOSTED_BASE_URL=https://heartbeat.sovereignengineering.io bun run hosted:smoke --strict-headers

Cloudflare Pages reads public/_headers during deployment. The active headers set CSP, referrer, frame, permissions, MIME-sniffing, and cache policy. Hashed Vite assets are immutable for one year; events.json and HTML revalidate.

Create a deploy hook in Cloudflare Pages under Settings > Builds > Deploy Hooks:

• Name: heartbeat-master-refresh
• Branch to build: master

Custom domain cutover:

1. Deploy and verify the Cloudflare Pages generated domain.
2. Add custom domain heartbeat.sovereignengineering.io in Cloudflare Pages.
3. Point DNS CNAME heartbeat to the generated <project>.pages.dev target shown by Cloudflare.
4. If CAA blocks certificate issuance, add these CAA values at the apex: issue "letsencrypt.org", issue "pki.goog; cansignhttpexchanges=yes", issue "ssl.com", issuewild "letsencrypt.org", issuewild "pki.goog; cansignhttpexchanges=yes", and issuewild "ssl.com".
5. Run the strict custom-domain smoke check:

bun run hosted:smoke https://heartbeat.sovereignengineering.io --strict-headers

6. Keep the previous hosting provider available for 24 hours as rollback.