CI/CD and Publishing
Relevant source files
The following files were used as context for generating this wiki page:
StatusBeam utilizes a modern CI/CD pipeline centered on Cloudflare's edge platform and GitHub Actions. The project is structured as a Bun-powered monorepo using Turborepo, designed to be deployed as a versioned package rather than a repository fork. This architecture ensures that users can upgrade their status pages through a CLI rather than complex upstream merges.
The publishing workflow is driven by release-please, which automates versioning and changelog generation based on Conventional Commits. The system is split into a "check layer" (cron-based monitoring), a "display layer" (Astro-based status page), and a "domain layer" (packages/core) that provides shared logic.
Sources: ARCHITECTURE.md:14-34, DEPLOYMENT.md:8-12, README.md:162-178
CI/CD Workflow Architecture
The CI/CD system handles three primary phases: validation (linting and testing), versioning/release management, and deployment orchestration.
Validation and Quality Gates
Every pull request triggers a suite of automated checks to ensure code quality. These include linting, unit testing via bun:test, and build verification. The project also integrates with SonarCloud and Codecov for static analysis and code coverage tracking.
Sources: CONTRIBUTING.md:21-27, ARCHITECTURE.md:150-155, README.md:1-5
Release Management
StatusBeam uses release-please to manage releases across its monorepo structure. It tracks changes in multiple packages and applications, automatically generating a consolidated pull request for version bumps and changelogs.
The diagram above illustrates the transition from developer commits to automated release artifacts.
Sources: release-please-config.json:1-55, ARCHITECTURE.md:164-165
Distribution Model
Unlike traditional status page generators that require users to fork the repository, StatusBeam is distributed as a set of versioned packages. Users scaffold their own projects using create-statusbeam, which depends on the core logic and CLI provided by the main repository.
Sources: DEPLOYMENT.md:8-12, ARCHITECTURE.md:161-163
Automated Publishing Components
The project publishes several distinct components, each with its own release configuration defined in release-please-config.json.
| Component | Package Name | Description |
|---|---|---|
| Core Logic | @statusbeam/core | Framework-free domain logic, schemas, and pure functions. |
| Worker App | @statusbeam/worker | The Cloudflare Cron Worker responsible for probing services. |
| Web App | @statusbeam/web | The Astro-based status page rendered at the edge. |
| CLI Tool | @statusbeam/cli | Orchestration tool for setup, deployment, and updates. |
| Scaffolder | create-statusbeam | Initial project creation tool for end-users. |
Sources: release-please-config.json:13-54, ARCHITECTURE.md:65-71
Deployment Pipelines
StatusBeam supports both manual and automated deployments targeting Cloudflare.
CI-Driven Deployment
For end-users, a scaffolded .github/workflows/deploy.yml runs the statusbeam deploy command on every push to the main branch. This requires CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets.
The sequence diagram shows the flow of an automated deployment triggered by a code push.
Sources: DEPLOYMENT.md:40-48, scripts/setup.sh:176-189
Provisioning and Setup
The statusbeam setup command (implemented via scripts/setup.sh in the monorepo) handles the initial infrastructure provisioning. It is idempotent and performs the following:
- Provisions D1 databases and KV namespaces.
- Configures
wrangler.jsoncfiles with resource IDs, custom domains, and cron schedules. - Applies initial SQL schemas to D1.
- Uploads the user's
status.config.ymlto KV.
Sources: scripts/setup.sh:77-160, DEPLOYMENT.md:20-27
Development Lifecycle Commands
Standardized commands are used across the repository to maintain consistency between local development and CI environments.
| Command | Purpose | File Context |
|---|---|---|
bun run lint | Runs linting and formatting checks. | CONTRIBUTING.md:25 |
bun run test | Executes unit tests with coverage reporting. | ARCHITECTURE.md:150, CONTRIBUTING.md:26 |
bun run build | Verifies the project builds successfully. | CONTRIBUTING.md:27 |
bun run deploy | Builds and deploys both Workers (Web + Worker). | scripts/setup.sh:187 |
statusbeam update | Bumps versioned dependencies to the latest release. | DEPLOYMENT.md:104-107 |
Infrastructure as Code (Wrangler Configuration)
The project utilizes wrangler.jsonc files to define the environment for Cloudflare Workers. These files are updated dynamically during the setup process to include specific resource IDs (UUIDs) generated by the Cloudflare API.
{
"scripts": {
"setup": "statusbeam setup",
"deploy": "statusbeam deploy",
"update": "statusbeam update"
},
"devDependencies": {
"@statusbeam/cli": "^1.0.0"
}
}
Note: Example derived from the scaffolded package.json structure.
Sources: packages/create-statusbeam/src/index.ts:119-131, scripts/setup.sh:122-127
Summary
The CI/CD and Publishing system for StatusBeam is designed for high reliability and ease of use. By leveraging release-please for monorepo management and a CLI-driven deployment model, the project maintains a separation between the core application logic and user-specific configurations. This allows the project to scale to many users while providing a seamless "package-based" upgrade path that avoids the pitfalls of repository forking.