Reusable Orun compositions for shipping a multi-tenant SaaS on Cloudflare — Pages sites, Workers, Turborepo packages, and the Terraform that backs them.
This repository is both:
- A composition catalog. Nine compositions under
stacks/stack-tectonic-flare/describe how a class of component is built, verified, and deployed. - A stack that publishes itself. Its own CI uses the
publish-stackcomposition to package the catalog and push it toghcr.io/sourceplane/saas-stack-tectonic-flare, so consumer repos can pin a version instead of copying YAML.
intent.yaml # environments, trigger bindings, composition sources
kiox.yaml / kiox.lock # pinned orun provider for the kiox workspace
.github/workflows/verify.yml # plan job -> matrix of orun jobs
stacks/stack-tectonic-flare/
stack.yaml # package identity: name, version, OCI registry target
component.yaml # the one component in this repo: publish this stack
compositions/<name>/
composition.yaml # what the composition is: schema, jobs, profiles
schema.yaml # JSON Schema for a component of this type
jobs/*.yaml # JobTemplate: the full ordered step list
profiles/*.yaml # ExecutionProfile: which capabilities run in which lane
README.md # generated-by-hand docs for consumers
| Composition | Use it for | Deploy mechanism | Docs |
|---|---|---|---|
cloudflare-pages |
A standalone static site in its own directory | Wrangler direct upload | README |
cloudflare-pages-turbo |
A Pages app inside a pnpm + Turborepo monorepo | Wrangler direct upload | README |
cloudflare-pages-terraform |
A standalone site whose Pages project is Git-connected | Terraform apply | README |
cloudflare-pages-turbo-terraform |
A monorepo Pages app whose project is Git-connected | Terraform apply | README |
cloudflare-worker |
A standalone Worker with its own install/build commands | wrangler deploy |
README |
cloudflare-worker-turbo |
A Worker inside a pnpm + Turborepo monorepo | wrangler deploy |
README |
turbo-package |
A shared library package — verification only | none | README |
terraform |
Standalone infrastructure — fmt, init, validate, plan | none | README |
publish-stack |
Publishing an Orun stack to an OCI registry | orun publish |
README |
Picking between the variants:
-turboor not? Use a-turbovariant when the component lives in a pnpm workspace and is built throughturbo run. Those compositions runpnpm installat the repo root and target the component with a Turbo filter. The plain variants take explicitinstallCommand/buildCommandstrings and run them insidesiteDir.-terraformor not? Use a-terraformvariant when the Cloudflare Pages project is Git-connected (Cloudflare builds on push, and Terraform owns the project resource). Use the plain variant when CI builds the assets and direct-uploads them with Wrangler.
Full stack-level conventions — the capability model, the shared profile lanes, and how the pieces
resolve — are in stacks/stack-tectonic-flare/README.md.
flowchart LR
E[GitHub event] --> T[trigger binding<br/>intent.yaml]
T --> V[environment<br/>dev / staging / production]
V --> P[profile per component<br/>component.yaml subscribe]
P --> C[capability filter]
C --> J[job steps that actually run]
- Trigger binding —
intent.yamlmaps a GitHub event to a planning scope. A pull request plans only changed components (base..head); av*tag plans everything. - Environment — each binding activates one environment, which carries a default lane, a namespace prefix, and approval policy.
- Profile — a component's
subscribe.environments[].profilepicks the execution profile for that environment; the environment'sdefaults.laneis the fallback for components that don't pin one. - Capabilities — the profile lists
includeCapabilities. Steps in the job template whosecapabilityis not in that list are dropped from the plan. One job template therefore serves the PR lane, the verify lane, and the deploy lane without branching inside the steps.
| Trigger | Event | Environment | Plan scope | Approval |
|---|---|---|---|---|
github-pull-request |
PR opened / synchronize / reopened / ready_for_review against main |
dev (dev-) |
changed only | no |
github-push-main |
push to main |
staging (stg-) |
changed only | yes |
github-tag-release |
push tag v* |
production (prod-) |
full | yes |
.github/workflows/verify.yml has two jobs:
planrunsorun plan --changed --from-ci github --event-file "$GITHUB_EVENT_PATH"and uploadsplan.json, exposing the planned jobs as a matrix.runfans out over that matrix, one runner per planned job, and executesorun run --plan plan.json --job <id> --remote-state. Check names look likestack-tectonic · staging · Publish.
If a change touches no component, the matrix is empty and the run job is skipped — that is a pass,
not a failure.
The workflow listens on push: branches: [main] and pull_request only, so the github-pull-request
and github-push-main bindings are the two that fire in this repo today. github-tag-release is
declared for consumers (and for a future tag-triggered workflow); pushing a v* tag here does not
start a run on its own.
Secrets consumed by the run job: ORUN_BACKEND_URL, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN,
SUPABASE_API_KEY, plus the workflow's GITHUB_TOKEN for GHCR login.
Point a consumer repo's intent.yaml at the published package instead of a local directory:
compositions:
sources:
- name: stack-tectonic-flare
kind: oci
ref: ghcr.io/sourceplane/saas-stack-tectonic-flare:2.1.0Then declare components against the composition types:
# apps/docs/component.yaml
apiVersion: sourceplane.io/v1
kind: Component
metadata:
name: docs-site
spec:
type: cloudflare-pages
subscribe:
environments:
- name: dev
profile: pull-request
- name: production
profile: deploy
inputs:
siteDir: apps/docs
installCommand: npm ci
buildCommand: npm run build
outputDir: dist
projectName: tectonic-docs
nodeVersion: "20"
productionBranch: mainTo read a published package without wiring an intent, download it:
orun fetch ghcr.io/sourceplane/saas-stack-tectonic-flare:2.1.0 --output ./tectonic-flareorun compositions list # what this catalog exports
orun composition cloudflare-worker -e # one composition, with every step expanded
orun plan --intent intent.yaml # what would run right now
cd stacks/stack-tectonic-flare && orun publish --dry-runorun publish resolves the package name, version, and registry from
stacks/stack-tectonic-flare/stack.yaml, so it must be run
from that directory (or with --root pointed at it).
The version lives in stacks/stack-tectonic-flare/stack.yaml. Publishing happens from CI when a change
to the stack lands on main: the stack-tectonic component subscribes to staging with the release
profile, which runs orun publish --dry-run and then the real orun publish.
-
Bump
metadata.versioninstacks/stack-tectonic-flare/stack.yaml. -
Merge to
main. Thestack-tectonic · staging · Publishcheck performs the upload. -
Verify the tag exists in the registry:
TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:sourceplane/saas-stack-tectonic-flare:pull&service=ghcr.io" | jq -r .token) curl -s -H "Authorization: Bearer $TOKEN" \ https://ghcr.io/v2/sourceplane/saas-stack-tectonic-flare/tags/list | jq
-
Tag the commit
vX.Y.Zto keep the git history aligned with the published versions.
Re-publishing an existing version is not meaningful — bump the version in the same PR that changes the
catalog, so every merge to main either publishes something new or publishes nothing.