Docs

Automation and CI/CD

Workflows, cron jobs, and release automation.

Automate the boring parts

CI/CD keeps releases, metrics, and syndication predictable. Each workflow is isolated, documented, and safe to re-run without damaging the main deployment.

GitHub Actions Semantic Release Cron Idempotent

Workflow matrix

Workflow	Trigger	Output
`.github/workflows/release.yml`	Push to `main`	Semantic release tag + GitHub release notes.
`.github/workflows/github-metrics.yml`	Cron (daily) + manual dispatch	Refreshes GitHub metrics history and commits updates.
`.github/workflows/syndicate.yml`	Posts/config changes + manual dispatch	Syndicates posts and opens a PR for state updates.
`vercel.json`	Vercel cron schedule	Calls `/api/github-metrics-update` for redundancy.
`/api/project-details-refresh`	GitHub Actions or manual webhook	Forces a project detail refresh for a specific repo.

Release pipeline

01. Conventional commits

Commit messages drive semantic-release versioning.
02. GitHub Actions run

Node 22 executes npx semantic-release on main.
03. Release notes

Tags and release notes are published in GitHub.

Metrics refresh pipeline

scripts/updateGithubMetrics.js powers the refresh logic.
.github/workflows/github-metrics.yml runs nightly and on demand.
The workflow uses a metrics store adapter (Postgres in production, SQLite locally).
Vercel cron calls /api/github-metrics-update as a redundant trigger.
Project detail refreshes can call /api/project-details-refresh?repo=OWNER/REPO.
scripts/ensureGithubMetrics.js runs before npm run dev to warm the snapshot when missing.
scripts/updateNugetPackages.js uses the NuGet search API plus data/projects.ts, data/projects.generated.ts, and the GitHub repo list to map packages to projects, writing data/nuget-packages.json.
scripts/updateProjectRepos.js syncs all owned GitHub repos into data/projects.generated.ts.
scripts/ensureBuildData.js runs before npm run build to refresh generated data older than 24 hours.

Syndication pipeline

Posts are cross-posted after merges to main or manual dispatch.
The workflow creates a PR for .syndication-state.json updates.
Errors do not block deployments (continue-on-error is enabled).
Full configuration details live in Syndication.

Local runbook

Command	Use case
`npm run metrics:update`	Refresh GitHub metrics history locally.
`npm run syndicate:dry-run`	Preview syndication without publishing.
`npm run syndicate -- --post=slug`	Publish a single post.
`npm run nuget:update`	Regenerate NuGet package mappings from the NuGet profile.
`npm run projects:update`	Sync owned GitHub repos into `data/projects.generated.ts`.

Optional environment

Variable	Use case
`NUGET_PROFILE`	Overrides the NuGet profile name used by the NuGet mapping script (defaults to `JerrettDavis`).
`NUGET_PROFILE_URL`	Full profile URL to scrape (useful if the profile slug differs).

Required secrets

GITHUB_TOKEN

HASHNODE_API_TOKEN

DEVTO_API_KEY

DATABASE_URL

METRICS_UPDATE_SECRET

PROJECT_DETAIL_REFRESH_SECRET

Ops Deployment

Hosting setup and environment configuration.

Signals Telemetry + APIs

Endpoints that workflows refresh.

Content Syndication

Detailed publishing pipeline for posts.

Quality Testing

Automated checks that guard releases.