NNO CI/CD Architecture

Blueprint for the continuous integration and deployment pipeline. All NNO services and apps are deployed via GitHub Actions using a self-hosted runner on DigitalOcean.

1. Infrastructure

Self-Hosted Runner

NNO uses a single self-hosted GitHub Actions runner to avoid GitHub's free-tier build minute limits and to benefit from a persistent dependency cache.

Why self-hosted? GitHub Actions free tier provides 2,000 minutes/month. The NNO monorepo has 7 Workers + 1 Pages app across 2 environments. A single deploy cycle takes ~10 minutes, exhausting free minutes within a week of active development. The DigitalOcean droplet costs ~$12/month and provides unlimited build minutes with faster installs (persistent pnpm store).

GitHub-Hosted Runner

Low-criticality workflows that don't need infrastructure access use ubuntu-latest:

• Publish Packages — Changesets versioning + GitHub Packages
• Claude Code — AI-assisted PR reviews and issue responses

2. Workflows

Overview

Concurrency Strategy

All workflows use concurrency groups to prevent duplicate runs:

Single runner bottleneck: Since all self-hosted workflows share one runner, jobs queue when the runner is busy. Production deploys (main) are never cancelled. Staging deploys (develop) can be cancelled by newer pushes to reduce queue buildup.

3. Deploy Workers Pipeline

The most complex workflow. Deploys all 7 Cloudflare Workers in strict dependency order.

Service Deployment Sequence

IAM ──> Billing ──> Registry ──> Provisioning ──> CLI Service ──> Stack Registry ──> Gateway
 │         │           │              │
 │         │           │              ├── Ensure CF Queues exist
 │         │           │              └── D1 migrations
 │         │           └── D1 migrations (depends on IAM + Billing bindings)
 │         └── D1 migrations
 └── D1 migrations

Why this order?

1. IAM first — all services depend on IAM for auth
2. Billing before Registry — Registry has NNO_BILLING service binding. CF API rejects deploys referencing Workers that don't exist yet
3. Provisioning after Registry — needs CF Queues pre-created before deploy
4. Gateway last — proxies all other services; must deploy after its upstream targets exist

Environment Resolution

The workflow resolves the target environment from the branch:

# Branch → Environment mapping
main    → is_prod=true,  env_flag=""        # wrangler deploy (no --env)
develop → is_prod=false, env_flag="--env stg"  # wrangler deploy --env stg

Each service's wrangler.toml defines [env.stg] with:

• Worker name with -stg suffix (e.g., nno-k3m9p2xw7q-gateway-stg)
• Service bindings pointing to -stg variants
• Separate D1 database IDs, KV namespace IDs
• ENVIRONMENT = "stg" var

Queue Provisioning

The Provisioning service requires CF Queues to exist before deploy. A pre-deploy step ensures they're created:

- name: Ensure CF Queues exist (Provisioning)
  run: |
    wrangler queues create "$QUEUE" 2>/dev/null || echo "Already exists"
    wrangler queues create "$DLQ"   2>/dev/null || echo "Already exists"

Queue names follow the Cloudflare naming convention: production = no suffix, staging = -stg.

4. Deploy Pages Pipeline

Builds and deploys the NNO Console app (React 19 + Vite) to Cloudflare Pages.

Environment Isolation

Each environment uses a separate CF Pages project (see dns-naming.md):

Why separate projects? CF Pages custom domains always route to the production deployment. A single project with preview branches cannot serve staging on a custom domain. See dns-naming.md for the Phase 3 routing worker alternative.

Build Pipeline

checkout → pnpm install → turbo build (packages) → vite build --mode {stg|prod} → wrangler pages deploy

Vite embeds VITE_* environment variables at build time. The .env.stg file points all service URLs to *.svc.stg.nno.app, while .env.prod points to *.svc.nno.app.

5. Auth Bundle Pipeline

Builds the auth Worker template (services/auth/) into a self-contained ESM bundle for per-platform deployment by the Provisioning service.

Trigger

• Push to main when services/auth/src/** files change
• Manual dispatch (workflow_dispatch)

Steps

checkout → pnpm install → esbuild (ESM, minified, ES2022) → R2 upload (versioned + latest) → update NNO_AUTH_BUNDLE_URL secret

R2 Storage

The NNO_AUTH_BUNDLE_URL secret is updated on both prod and stg Provisioning Workers to point to the latest bundle URL.

Prerequisites: R2 bucket nno-k3m9p2xw7q-auth-bundles must exist. Custom domain auth-bundles.nno.app must be configured on the bucket.

6. CI Pipeline

Runs on pull requests and merge groups. Does not run on main/develop push (Deploy Workers handles validation for those branches).

Quality Gates

steps:
  - pnpm install --frozen-lockfile
  - pnpm turbo build          # Build all packages
  - pnpm lint                 # ESLint across workspace
  - pnpm typecheck            # tsc --noEmit across workspace
  - pnpm format:check         # Prettier check
  - pnpm test                 # Vitest (filtered to: core, sdk, ui-auth, billing, iam)

Test Filtering

Tests run only for packages with stable test suites:

"test": "turbo test --filter=@neutrino-io/{core,sdk,ui-auth,service-billing,service-iam}"

This avoids CI failures from packages with incomplete or flaky test coverage.

7. Package Publishing

Manages versioning and publishing of @neutrino-io/* packages to GitHub Packages.

Flow

1. Developer adds a changeset: pnpm changeset
2. On merge to main, changesets/action creates a version bump PR
3. When the version PR is merged, packages are published to GitHub Packages

8. Secrets

Service-Level Secrets (set via wrangler secret put)

9. Build System (Turborepo)

The monorepo uses Turborepo for task orchestration with dependency-aware caching.

Task Graph

         ┌──────────┐
         │  build   │ ← depends on ^build (upstream packages)
         └────┬─────┘
              │
    ┌─────────┼──────────┐
    │         │          │
┌───▼──┐ ┌───▼────┐ ┌───▼───┐
│ lint │ │typecheck│ │ test  │ ← all depend on ^build
└──────┘ └────────┘ └───────┘

Configuration (turbo.json)

{
  "globalEnv": ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"],
  "globalDependencies": [".env", "apps/console/.env.stg", "apps/console/.env.prod"],
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "lint": { "dependsOn": ["^build"] },
    "typecheck": { "dependsOn": ["^build"] },
    "test": { "dependsOn": ["^build"] },
    "dev": { "persistent": true, "cache": false }
  },
  "concurrency": "50%"
}

10. Scaling Considerations

Current Limitations

Future Improvements (Phase 3)