CI/CD Ship & operate

Use GitHub workflows as thin orchestration around explicit Devflare deploy and validation actions

This repository keeps GitHub workflows small on purpose: caller workflows own triggers, permissions, and package selection, while shared Devflare actions handle impact checks, deploy execution, and feedback publishing.

The CI/CD pattern in this repo is intentionally boring in the best way. One workflow validates the workspace, preview workflows decide whether a package is affected before they deploy, production workflows verify what went live, and shared actions keep the mechanics consistent across packages.

Best for: GitHub Actions workflows that validate packages and run explicit preview or production deploys
Core split: Caller workflow owns policy; shared actions own mechanics
Package selector: chooses which Devflare config actually deploys

Keep GitHub workflows thin and let the actions do the repeatable work

The repo uses GitHub Actions as orchestration, not as a second deploy framework. The workflow file decides when the job runs, which permissions it gets, and which package it is targeting. The reusable actions then handle impact calculation, dependency installation, deploy execution, and GitHub feedback in a consistent way.

That split matters because it keeps policy visible in the workflow while the mechanics stay reusable. A docs preview, a testing preview family, and a production deploy can share the same action vocabulary without pretending they are the same deployment shape.

Use workflow triggers and path filters to decide whether a lane should even run.
Use to make the target package visible in the workflow itself.
Keep preview versus production intent explicit instead of hiding it inside a generic shell script.
Use workflow summaries and feedback actions so the result is observable without re-reading raw logs every time.

A good workflow review question

Ask three things separately: what triggered this workflow, which package is it acting on, and which explicit deploy target will the action use?

Use one workspace CI lane for cached validation, not for hidden deploy logic

is the repo-wide validation lane. It reacts to workspace-level changes, restores Bun and Turborepo caches, installs dependencies once, and runs the cached lane from the repo root.

That workflow proves the workspace still builds, checks, and tests coherently. It does not choose a Cloudflare target or quietly deploy anything on your behalf.

workspace-ci.yml

Repo-wide cached validation for apps, cases, and packages before any package-specific deploy lane runs.

Workspace CI stays in the validation lane

The active file is the real repo workflow under `.github/workflows/workspace-ci.yml`, and the surrounding tree shows the workflow family this page references.

on:

pull_request:

paths:

- 'apps/documentation/**'

- 'cases/**'

- 'packages/**'

push:

branches:

- main

- next

workflow_dispatch:

jobs:

validate:

steps:

- uses: actions/checkout@v5

- uses: oven-sh/setup-bun@v2

- shell: bash

run: bun run devflare:ci

Preview and production workflows should resolve impact before they deploy

The repository preview and production workflows call before they deploy. That action compares the target package against the relevant git range so the workflow can skip Cloudflare work when the package or its important dependencies did not change, and it also accepts when shared files outside the package root should still invalidate the deploy.

When a deploy is needed, the workflow hands the package path and explicit target to . That action enforces the deploy target rules, installs dependencies from the right place, runs the deploy command, captures preview aliases or version ids, and publishes a structured summary for the workflow run.

The reusable action metadata in this repo still exposes a input for same-worker preview uploads, and the live documentation PR workflow below still threads that deprecated input through the deploy action. Treat that as current repo drift rather than a recommended pattern: itself no longer accepts , so new workflows should prefer for same-worker uploads or for named preview deploys until the shared action and caller workflows are cleaned up.

The documentation workflow family is the clearest repo-local example to study because PR previews, branch previews, production deploys, and branch cleanup all live as separate files.

documentation-preview-pr.yml

PR-scoped docs preview with a stable PR comment that gets updated in place.

documentation-preview-branch.yml

Branch push preview for the docs app when there is no PR requirement.

documentation-production.yml

Explicit docs production deploy lane with live verification after deploy.

Use , , or exactly once per deploy action call.
Use on the impact action when shared workspace files outside the package root should still trigger a redeploy.
Use when a package-local deploy should reuse one shared root install in a monorepo.
Let the workflow pass branch names, preview scopes, and messages explicitly so deploy intent is visible in logs.
Use package-specific workflows when the preview model differs, like PR-scoped docs previews versus branch-scoped multi-worker preview families.

Current repo example, not the future-safe pattern

The live file still passes , and its closed-PR cleanup job still retires metadata with . Treat that as repository drift under cleanup, not as the shape to copy into new workflows.

The documentation PR preview workflow resolves impact, then runs an explicit deploy

This abridged excerpt intentionally shows the current repo workflow, including the stale `preview-alias` wiring. It omits repeated auth details and the separate closed-PR cleanup job, which still needs the same alias-flag cleanup.

on:

pull_request:

types: [opened, synchronize, reopened, ready_for_review, closed]

jobs:

deploy-preview:

steps:

- name: Resolve documentation PR preview impact

id: impact

uses: ./.github/actions/devflare-deploy-impact

with:

target-package: documentation

- name: Deploy documentation PR preview

id: deploy

if: \${{ steps.impact.outputs.should-deploy == 'true' }}

uses: ./.github/actions/devflare-deploy

with:

working-directory: apps/documentation

install-working-directory: .

deploy-command: bun run deploy --

preview: 'true'

preview-alias: \${{ env.DOCUMENTATION_PR_PREVIEW_ALIAS_PREFIX }}-\${{ github.event.pull_request.number }}

- name: Publish documentation PR preview feedback

uses: ./.github/actions/devflare-github-feedback

with:

mode: comment

comment-key: documentation-preview

Publish feedback and verify the live result instead of treating the deploy log as the whole story

After deploy, the workflows in this repo publish GitHub feedback on purpose. Preview workflows update a stable PR comment in place, while production workflows can publish a GitHub deployment record and verify that the expected build is actually visible on the live site.

This is where thin workflows pay off: reporting stays separate from deploy mechanics, and a failed live verification can be surfaced cleanly without hiding inside one giant shell step.

Keep the reusable action outputs in mind too: returns , , , , , and ; returns , , , , , , , and ; and returns , , and for later jobs that need to update, retire, or cross-link that feedback.

Use for PR comments, GitHub deployments, or both.
Keep preview aliases or production URLs visible in workflow output so reviewers do not need to scrape logs.
Fail the workflow explicitly when deploy verification or live verification says the result is not trustworthy.
Use to leave a small readable outcome instead of forcing readers to decode every raw step.

Workflow file	When it runs	GitHub feedback
	Docs pull requests into the default branch	Stable PR comment updated in place.
	Non-default branch pushes that affect the docs app	GitHub deployment updated with the current branch preview URL.
	Default branch pushes or manual dispatch for docs production	Production deployment record plus live URL verification.
	Testing pull requests into the default branch	Stable PR comment for the PR-scoped preview family.
	Non-default branch pushes that affect the testing app or workers	GitHub deployment, plus the PR comment when that branch belongs to an open PR.
and closed-PR cleanup jobs	Deleted branches or closed pull requests	Marks preview feedback inactive after retirement and cleanup.

What the repo pattern optimizes for

Clear triggers, explicit targets, reusable actions, and observable feedback make CI/CD easier to trust when a deploy matters.

Cleanup workflows should be visible too, not hidden in one-off scripts

This repo keeps cleanup as first-class automation. Deleted branches have dedicated cleanup workflows, while PR-scoped previews clean themselves up through a job inside the matching PR workflow when the pull request closes.

The current documentation PR cleanup job still retires metadata with , which the CLI no longer accepts. Use in new automation and treat that repo job as pending cleanup instead of current best practice.

That keeps teardown reviewable: you can see which file retires preview metadata, which one deletes preview-owned Cloudflare resources or Workers, and which one marks GitHub feedback inactive instead of leaving old preview links pretending they still mean something.

documentation-preview-branch-cleanup.yml

Retires documentation branch preview metadata after branch deletion or manual dispatch.

testing-preview-branch-cleanup.yml

Retires testing branch preview metadata, deletes preview Workers and resources, and marks feedback inactive.

documentation-preview-pr.yml

Also contains the closed-PR cleanup job for the stable documentation preview comment.

testing-preview-pr.yml

Also contains the closed-PR cleanup job for the testing preview family.

Branch deletion cleanup lives in dedicated files so the trigger is obvious from the filename.
PR closure cleanup lives beside the PR preview deploy job so the open-and-close lifecycle stays in one file.
Cleanup retires preview records first, then removes preview-owned infrastructure, then marks GitHub feedback inactive.

The testing branch cleanup workflow retires metadata, removes preview resources, and closes the feedback loop

This abridged excerpt is the real branch cleanup lane under `.github/workflows/testing-preview-branch-cleanup.yml`. It omits repeated auth and feedback inputs so the lifecycle steps stay visible.

on:

delete:

workflow_dispatch:

inputs:

branch:

description: Branch name to clean up manually

required: true

type: string

jobs:

cleanup-preview:

steps:

- name: Retire tracked testing branch preview metadata

shell: bash

run: bunx --bun devflare previews retire --worker "$MAIN_WORKER_NAME" --branch "$PREVIEW_BRANCH" --apply

- name: Delete preview-scoped testing Cloudflare resources

shell: bash

run: |

cd apps/testing

bunx --bun devflare previews cleanup-resources --scope "$PREVIEW_BRANCH" --apply

- name: Mark testing branch preview deployment inactive

uses: ./.github/actions/devflare-github-feedback

Multi-worker preview families still deploy package by package

The testing preview workflows show the multi-worker version of the same rule. They keep one shared preview scope like , but still deploy each worker package separately with its own .

That is the important CI/CD habit for multi-worker systems: one workflow can coordinate the family, but each package still owns its own resolved Devflare config and deploy step.

is also the repo example of branch pushes updating both a GitHub deployment and, when the branch already belongs to an open pull request, the stable PR comment through the same workflow run.

testing-preview-pr.yml

PR-scoped testing preview family with one explicit preview scope per pull request.

testing-preview-branch.yml

Branch-scoped testing preview family that can refresh both deployment feedback and the PR comment.

Branch-scoped multi-worker previews stay package-local

This excerpt comes from `.github/workflows/testing-preview-branch.yml`, which fans one explicit preview scope across the testing worker family.

env:

DEVFLARE_PREVIEW_BRANCH: '\${{ github.ref_name }}'

jobs:

deploy-preview:

steps:

- uses: ./.github/actions/devflare-deploy

with:

working-directory: apps/testing/workers/auth-service

install-working-directory: .

preview-scope: \${{ env.DEVFLARE_PREVIEW_BRANCH }}

- uses: ./.github/actions/devflare-deploy

with:

working-directory: apps/testing/workers/search-service

install-working-directory: .

preview-scope: \${{ env.DEVFLARE_PREVIEW_BRANCH }}

- uses: ./.github/actions/devflare-deploy

with:

working-directory: apps/testing

install-working-directory: .

preview-scope: \${{ env.DEVFLARE_PREVIEW_BRANCH }}

- uses: ./.github/actions/devflare-github-feedback

with:

mode: both

resolve-pr-from-ref: 'true'

SvelteKit

Point Devflare at SvelteKit’s Cloudflare worker output—often via , but sometimes by handing the adapter worker directly—keep in , and compose into so local platform bindings line up with the Worker runtime Devflare manages.

Production deploys

Devflare keeps build and deploy flows inspectable, but deploys are intentionally explicit: production uses or , while preview is either a same-worker upload with plain or a named preview scope with .