Skip to content

CI/CD & Deployment

SMACKZ uses GitHub Actions for CI/CD and deploys backend services to Control Plane (cpln), with frontend apps on Cloudflare Pages.

Deployment Targets

Service Platform Trigger
Yum Backend Control Plane Push to qa, staging, main
POS Adapters Control Plane Push to qa, staging, main
MCP Server/Gateway Control Plane Push to qa, staging, main
KDS-Web Control Plane Push to qa, staging, main
Lakehouse (Writer, Query, Metabase) Control Plane Push to qa, staging, main
Smackz-Admin Cloudflare Pages Push to qa, staging, main
Smackz-Websites Cloudflare Pages Push to qa, staging, main
Shared packages GitHub Packages Push to qa, main

Shared Package Publishing

Three packages are published to GitHub Packages:

Package Repo
@smackz-llc/shared-core shared-core
@smackz-llc/shared-ui shared-ui
@smackz-llc/page-renderer page-renderer

Version Strategy

Branch Version npm Tag Example
main X.Y.Z latest 2.0.5
qa X.Y.Z-qa.{run} qa 2.0.5-qa.17

On qa push, the workflow appends -qa.${GITHUB_RUN_NUMBER} and publishes with --tag qa. On main push, it publishes the version from package.json as-is.

Build Order

When pushing changes to qa across packages:

  1. Push shared-core first, wait for completion
  2. Push shared-ui (auto-picks up new shared-core@qa)
  3. page-renderer is independent

How Dependent Apps Get QA Packages

Cloudflare Pages (Admin, Websites)

A prebuild script checks CF_PAGES_BRANCH:

  • qa branch: installs @smackz-llc/shared-core@qa, shared-ui@qa
  • Other branches: uses locked versions from package-lock.json

GitHub Actions (Restaurant-Websites)

A conditional workflow step overrides packages on qa branch deploys.

Control Plane Deployment

Backend services deploy to Control Plane using:

  • .cpln/cpln-workload.yaml -- Workload definition
  • .cpln/cpln-secret-policy.yaml -- Secret access policies
  • .github/workflows/deploy-to-control-plane.yml -- Deploy workflow

The smackz GVC (Global Virtual Cloud) is managed by Yum's deployment. Other services share it -- do not create duplicate GVC configs.

CI/CD Pipeline Steps

  1. Build -- TypeScript compilation, linting, type checking
  2. Docker -- Build and push container image to registry
  3. Deploy -- Apply cpln workload YAML with environment-specific substitutions
  4. Verify -- Health check on deployed service

Authentication

Context Token Scope
Publishing packages GITHUB_TOKEN (auto) Write to own repo
Installing own-repo packages GITHUB_TOKEN (auto) Read own repo
Installing cross-repo packages PACKAGES_READ_TOKEN (Classic PAT) read:packages across org

Verification Commands

# Check latest QA version of a package
npm view @smackz-llc/shared-core --tag qa

# Check latest stable version
npm view @smackz-llc/shared-core --tag latest

Key Files

  • docs/CI-CD-Workflows.md -- Full CI/CD documentation
  • yum/.github/workflows/deploy-to-control-plane.yml -- Example deploy workflow
  • yum/.cpln/cpln-workload.yaml -- Example workload config
  • shared-core/.github/workflows/publish.yml -- Package publish workflow