Skip to content
SiteSwarm Platform Documentation

Ci Deployment Environments

Deployment Environments, GitHub Environments & Promotion Pipeline

1. Executive Summary & Environment Topology

SiteSwarm separates application execution across five environment tiers, including a dedicated 3-Tier Non-Production Taxonomy (NON_PRODUCTION_ENVIRONMENT_TAXONOMY.md). Cloud-deployed tiers map 1-to-1 to native GitHub Actions Environments (preview, staging, and production) so credentials, branch restrictions, promotion gates, and deployment audit trails are enforced mechanically by GitHub.

flowchart LR
    Local["1. Local Dev\n(localhost:<port> / No GitHub Env)"] --> PRPreview["2a. Ephemeral PR Preview\n(GitHub Env: 'preview')"]
    Local --> ClientPreview["2b. Long-Lived Client Preview\n(GitHub Env: 'preview')"]
    PRPreview -->|"PR Merged to main + 'Gate' Green"| Staging["3. Internal Staging\n(GitHub Env: 'staging')"]
    Staging -->|"'Staging Gate' Green + Promotion"| Prod["4. Production\n(GitHub Env: 'production')"]
Environment Tier GitHub Environment (environment:) URL / Hostname Pattern Promotion Gate, Audience & Lifecycle
1. Local Development None (Offline Local Machine) http://localhost:<dynamic-port> Offline local development with Miniflare binding emulation and .dev.vars.
2a. Ephemeral PR Preview preview (preview-deploy.yml) https://<app>-preview-pr-<N>.<workers-domain> Opt-in on Pull Requests (preview-deploy label or manual dispatch); automatically torn down on PR close/merge (CI_EPHEMERAL_PREVIEWS.md).
2b. Long-Lived Client Preview preview (client-preview-deploy.yml) https://<app>-preview.<platform-domain> & https://<app>.preview.<platform-domain> Deployed for sales demonstrations and prospect testing; storefront is unblocked while /admin* routes stay behind Zero Trust; persists independently of PR teardown (NON_PRODUCTION_ENVIRONMENT_TAXONOMY.md).
3. Internal Staging staging (staging-deploy.yml) https://<app>-staging.<platform-domain> Restricted to main after the Gate status check passes; deploys on a debounced schedule or manual dispatch, strictly gated behind Cloudflare Zero Trust, and emits Staging Gate.
4. Production production (production-promote.yml) https://www.<client-domain>.com Restricted to main; requires both Gate and Staging Gate status checks to be green on the target commit SHA before promoting to live client Custom Hostnames (CLOUDFLARE_FOR_PLATFORMS_AND_DOMAIN_INGRESS.md).

2. How GitHub Environments Govern Cloud Deployments

Configuring environment: preview | staging | production on deployment jobs in .github/workflows/ provides four platform guarantees:

  1. Environment-Scoped Secrets & Variables: Deployment credentials (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID) and environment variables are scoped per GitHub Environment rather than exposed globally to every untrusted workflow job.
  2. Branch & Promotion Protection Rules: While the preview GitHub Environment permits deployments from Pull Request branches (when opted in via preview-deploy or client-preview), the staging and production GitHub Environments restrict deployments strictly to main and support required reviewer approvals or wait timers in Repository Settings $\to$ Environments.
  3. Sequential Commit Attestation (Gate $\to$ Staging Gate $\to$ Production):
    • Before deploying to environment: staging, staging-deploy.yml verifies that the commit SHA has passed the CI Gate check (CI_CHANGE_DETECTION.md).
    • Before promoting to environment: production, production-promote.yml verifies that the exact commit SHA has passed both Gate and Staging Gate, preventing unvalidated commits from bypassing staging.
  4. Native Deployment History & Active URL Tracking: GitHub automatically records each deployment run, active commit SHA, and environment URL under the repository’s Deployments dashboard.

3. Strict Isolation Between Custom Hostnames and Non-Production Environments

A client’s custom domain (www.<client-domain>.com) is bound exclusively to the production environment Worker deployment. Non-production environments (staging, preview, and client-preview) are never accessible from the client’s custom hostname and run strictly under SiteSwarm’s platform domain (<app>-staging.<platform-domain>, <app>-preview.<platform-domain>), dedicated preview zone (<app>.preview.<platform-domain>), or Workers dev domain (<app>-preview-pr-<N>.<workers-domain>) using the single-level hyphenated subdomain convention required for free Universal SSL coverage (see CLOUDFLARE_FOR_PLATFORMS_AND_DOMAIN_INGRESS.md and NON_PRODUCTION_ENVIRONMENT_TAXONOMY.md).

4. Branch Protection & Integration Ruleset Guarantees

GitHub Environments operate in lockstep with repository branch protection rulesets defined declaratively in .github/branch-ruleset.json and audited via scripts/sync-branch-protection.ts:

  1. Trunk Isolation on main:
    • Direct pushes and force-pushes to refs/heads/main are blocked via GitHub Repository Ruleset deletion and non_fast_forward rules.
    • All changes to main must enter via Pull Request (pull_request rule).
  2. Mandatory Core Gates & Mechanical Merge Latch:
    • Every Pull Request requires 100% green status checks across:
      • Gate: CI workflow consolidation aggregator (CI_CHANGE_DETECTION.md).
      • Evaluate Monorepo Changes: Monorepo change detection and canary scoping.
      • governance/two-stage-review: Independent Stage 1 Tactical and Stage 2 Strategic subagent review attestations.
    • Merging is strictly attested and executed through the mechanical merge latch (pnpm run merge <PR_NUMBER> / scripts/merge-guard.ts). Raw gh pr merge is prohibited.
  3. Developer & Agent Working Patterns:
    • Operational worktree isolation protocols, local dev tooling, and review procedures are detailed in DEVELOPMENT.md.

Decisions Intentionally Deferred

  • Exact JSON ruleset payloads and CLI synchronization flags live in .github/branch-ruleset.json and scripts/sync-branch-protection.ts rather than architectural prose to avoid configuration drift.