Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/workflows/verify.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ jobs:
with:
fetch-depth: 0
- uses: sourceplane/orun-action@v1.2.0
with:
# Match the orun pinned in kiox.lock. The action defaults to `latest`,
# which drifted to v2.38.0 and fails remote-state OIDC exchange with 403.
version: v1.26.0
- run: |
orun plan \
--changed \
Expand Down Expand Up @@ -56,6 +60,8 @@ jobs:
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: sourceplane/orun-action@v1.1.0
with:
version: v1.26.0
- run: |
orun run \
--plan plan.json \
Expand Down
183 changes: 183 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
# stack-tectonic-flare

Reusable [Orun](https://github.com/sourceplane/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:

1. **A composition catalog.** Nine compositions under [`stacks/stack-tectonic-flare/`](stacks/stack-tectonic-flare)
describe how a class of component is built, verified, and deployed.
2. **A stack that publishes itself.** Its own CI uses the `publish-stack` composition to package the
catalog and push it to
[`ghcr.io/sourceplane/saas-stack-tectonic-flare`](https://github.com/sourceplane/stack-tectonic-flare/pkgs/container/saas-stack-tectonic-flare),
so consumer repos can pin a version instead of copying YAML.

## Repository layout

```
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
```

## The catalog

| Composition | Use it for | Deploy mechanism | Docs |
|---|---|---|---|
| [`cloudflare-pages`](stacks/stack-tectonic-flare/compositions/cloudflare-pages) | A standalone static site in its own directory | Wrangler direct upload | [README](stacks/stack-tectonic-flare/compositions/cloudflare-pages/README.md) |
| [`cloudflare-pages-turbo`](stacks/stack-tectonic-flare/compositions/cloudflare-pages-turbo) | A Pages app inside a pnpm + Turborepo monorepo | Wrangler direct upload | [README](stacks/stack-tectonic-flare/compositions/cloudflare-pages-turbo/README.md) |
| [`cloudflare-pages-terraform`](stacks/stack-tectonic-flare/compositions/cloudflare-pages-terraform) | A standalone site whose Pages project is Git-connected | Terraform apply | [README](stacks/stack-tectonic-flare/compositions/cloudflare-pages-terraform/README.md) |
| [`cloudflare-pages-turbo-terraform`](stacks/stack-tectonic-flare/compositions/cloudflare-pages-turbo-terraform) | A monorepo Pages app whose project is Git-connected | Terraform apply | [README](stacks/stack-tectonic-flare/compositions/cloudflare-pages-turbo-terraform/README.md) |
| [`cloudflare-worker`](stacks/stack-tectonic-flare/compositions/cloudflare-worker) | A standalone Worker with its own install/build commands | `wrangler deploy` | [README](stacks/stack-tectonic-flare/compositions/cloudflare-worker/README.md) |
| [`cloudflare-worker-turbo`](stacks/stack-tectonic-flare/compositions/cloudflare-worker-turbo) | A Worker inside a pnpm + Turborepo monorepo | `wrangler deploy` | [README](stacks/stack-tectonic-flare/compositions/cloudflare-worker-turbo/README.md) |
| [`turbo-package`](stacks/stack-tectonic-flare/compositions/turbo-package) | A shared library package — verification only | none | [README](stacks/stack-tectonic-flare/compositions/turbo-package/README.md) |
| [`terraform`](stacks/stack-tectonic-flare/compositions/terraform) | Standalone infrastructure — fmt, init, validate, plan | none | [README](stacks/stack-tectonic-flare/compositions/terraform/README.md) |
| [`publish-stack`](stacks/stack-tectonic-flare/compositions/publish-stack) | Publishing an Orun stack to an OCI registry | `orun publish` | [README](stacks/stack-tectonic-flare/compositions/publish-stack/README.md) |

Picking between the variants:

- **`-turbo` or not?** Use a `-turbo` variant when the component lives in a pnpm workspace and is built
through `turbo run`. Those compositions run `pnpm install` at the repo root and target the component
with a Turbo filter. The plain variants take explicit `installCommand` / `buildCommand` strings and
run them inside `siteDir`.
- **`-terraform` or not?** Use a `-terraform` variant 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`](stacks/stack-tectonic-flare/README.md).

## How a run is produced

```mermaid
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]
```

1. **Trigger binding** — `intent.yaml` maps a GitHub event to a planning scope. A pull request plans only
changed components (`base..head`); a `v*` tag plans everything.
2. **Environment** — each binding activates one environment, which carries a default lane, a namespace
prefix, and approval policy.
3. **Profile** — a component's `subscribe.environments[].profile` picks the execution profile for that
environment; the environment's `defaults.lane` is the fallback for components that don't pin one.
4. **Capabilities** — the profile lists `includeCapabilities`. Steps in the job template whose
`capability` is 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 |

## CI

[`.github/workflows/verify.yml`](.github/workflows/verify.yml) has two jobs:

- **`plan`** runs `orun plan --changed --from-ci github --event-file "$GITHUB_EVENT_PATH"` and uploads
`plan.json`, exposing the planned jobs as a matrix.
- **`run`** fans out over that matrix, one runner per planned job, and executes
`orun run --plan plan.json --job <id> --remote-state`. Check names look like
`stack-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.

## Consuming the catalog

Point a consumer repo's `intent.yaml` at the published package instead of a local directory:

```yaml
compositions:
sources:
- name: stack-tectonic-flare
kind: oci
ref: ghcr.io/sourceplane/saas-stack-tectonic-flare:2.1.0
```

Then declare components against the composition types:

```yaml
# 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: main
```

To read a published package without wiring an intent, download it:

```bash
orun fetch ghcr.io/sourceplane/saas-stack-tectonic-flare:2.1.0 --output ./tectonic-flare
```

## Local development

```bash
orun 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-run
```

`orun publish` resolves the package name, version, and registry from
[`stacks/stack-tectonic-flare/stack.yaml`](stacks/stack-tectonic-flare/stack.yaml), so it must be run
from that directory (or with `--root` pointed at it).

## Releasing

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`.

1. Bump `metadata.version` in `stacks/stack-tectonic-flare/stack.yaml`.
2. Merge to `main`. The `stack-tectonic · staging · Publish` check performs the upload.
3. Verify the tag exists in the registry:

```bash
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
```

4. Tag the commit `vX.Y.Z` to 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.
142 changes: 142 additions & 0 deletions stacks/stack-tectonic-flare/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Tectonic Flare Platform Stack

Package identity, from [`stack.yaml`](stack.yaml):

| | |
|---|---|
| Stack name | `tectonic-flare` |
| Version | `2.1.0` |
| Owner | `sourceplane` |
| Registry | `ghcr.io/sourceplane/saas-stack-tectonic-flare` (public) |
| Compositions | 9 |

This directory is the publishable unit. `orun publish` reads `stack.yaml` from here, archives the
tree, and pushes it to the registry above under the tag in `metadata.version`.

## Anatomy of a composition

Every composition is four files that answer four separate questions:

| File | Kind | Question it answers |
|---|---|---|
| `composition.yaml` | `Composition` | What is this type called, which schema validates it, which jobs and profiles exist, and what are the defaults? |
| `schema.yaml` | `ComponentSchema` | What inputs may a component of this type set, and which are required? |
| `jobs/*.yaml` | `JobTemplate` | What is the complete, ordered list of steps — every step any profile could run? |
| `profiles/*.yaml` | `ExecutionProfile` | For a given lane, which of those steps actually run, and under what policy? |

The split matters: **the job template is written once, with every step**, and profiles subtract from it.
There is no `if PR then skip` logic in the step list. A step is selected purely by whether its
`capability` appears in the profile's `includeCapabilities`.

```yaml
# jobs/cloudflare-worker-verify-deploy.yaml (excerpt)
steps:
- id: build-worker
capability: cloudflare-worker.build # <- selector
run: "{{.buildCommand}}"

# profiles/cloudflare-worker-pull-request.yaml (excerpt)
jobs:
verify-deploy:
includeCapabilities:
- cloudflare-worker.build # <- included, so the step runs
# cloudflare-worker.deploy omitted, so deploy is not planned at all
```

Capabilities are namespaced by composition type (`cloudflare-worker.build`, not `build`), so two
compositions in the same plan never collide.

## Profile lanes

Names are consistent across the catalog so a component can subscribe to the same lane everywhere:

| Lane | Present in | Meaning |
|---|---|---|
| `pull-request` | all deploy-capable compositions | Cheapest useful signal on a PR: set up, install, build, verify. Never mutates a remote. |
| `verify` | all | Full non-mutating verification. Same shape as `pull-request` plus anything slow but safe (Terraform `init` / `validate`). |
| `quick-check` | `turbo-package` | Structure-only smoke: install and check the package exists, skipping build and typecheck. |
| `deploy` | direct-upload compositions | `verify` plus provision and deploy. |
| `release` | Terraform-backed compositions, `publish-stack` | `verify` plus the mutating apply/publish, gated by profile policies. |
| `dry-run` | `publish-stack` | Validation-only publish (`orun publish --dry-run`). |

`release` profiles carry policies that the runner enforces before the mutating step:
`requireCleanGitTree`, `requirePinnedTerraformVersion`, `requireApproval`.

## Two layers of gating

Profiles decide **whether a mutating step is planned**. The steps themselves add a second guard, so a
misrouted plan still cannot deploy from the wrong place. Every deploy and apply step in this catalog
starts with:

```bash
if [ "{{.Environment}}" != "production" ] || [ "${GITHUB_REF:-}" != "refs/heads/{{.productionBranch}}" ]; then
echo "Skipping ..."; exit 0
fi
```

So a live deploy requires **all** of: a profile that includes the deploy capability, the `production`
environment, and `GITHUB_REF` on the component's `productionBranch`. Anywhere else the step exits 0
with a skip notice. The Worker compositions add one more case: in the `dev` environment they run
`wrangler deploy --dry-run` instead of skipping outright, so PRs get real Wrangler validation.

Credentials are asserted only after that gate passes (`: "${CLOUDFLARE_API_TOKEN:?...}"`), which is why
the verify lanes run fine on forks and locally with no Cloudflare secrets present.

## Template context

Step `run` blocks are Go templates. Available keys:

| Key | Source |
|---|---|
| `{{.Environment}}` | The environment the job was planned into — `dev`, `staging`, `production` |
| `{{.Component}}` | The component's name, used in the log notices |
| `{{.anyInput}}` | Any input the component set, validated against `schema.yaml` |

Optional inputs are guarded with `{{if .foo}}…{{else}}…{{end}}` so an unset input degrades to a
documented default or an explicit skip, never to an empty command.

## Conventions to keep when adding a composition

1. **One job template per composition.** Add capabilities, not job templates, when a lane needs more.
2. **Name capabilities `<type>.<verb>`** and list every one of them in the template's `capabilities:`
block as well as on the step.
3. **Required vs optional inputs.** Anything a step interpolates unconditionally belongs in the schema's
`required:` list. Anything wrapped in `{{if}}` must not be required.
4. **`additionalProperties: false`** on `inputs` — a typo in a consumer's `component.yaml` should fail
validation, not silently disappear.
5. **`onFailure: stop`** on every step that gates correctness.
6. **Gate mutating steps** on `{{.Environment}}` and `productionBranch` as shown above, even though the
profile already excludes them from non-deploy lanes.
7. **Update the composition's `README.md`** in the same change — the profile/capability tables there are
the consumer-facing contract.

## Versioning and publishing

`metadata.version` in `stack.yaml` is the published OCI tag. Bump it in the same PR that changes any
composition:

| Change | Bump |
|---|---|
| Docs, comments, descriptions | patch |
| New composition, new profile, new optional input | minor |
| Removed or renamed input/profile/capability, or a required input added | major |

Merging to `main` runs the `stack-tectonic · staging · Publish` check, which dry-runs and then publishes.
See the [repository README](../../README.md#releasing) for the full release and verification steps.

## Component contract for this repo

[`component.yaml`](component.yaml) declares the single component that publishes this catalog:

```yaml
spec:
type: publish-stack
subscribe:
environments:
- name: dev
profile: dry-run # PRs validate the package
- name: staging
profile: release # merge to main publishes
- name: production
profile: release
```
Loading
Loading