---
title: "GitHub & CI/CD"
description: "GitHub environments, workflows, and Conductor workspace automation"
source: /docs/github
---


Overview [#overview]

When you select GitHub during scaffolding, your project ships with a complete CI/CD pipeline:

* **3 GitHub Environments** — development, preview, production
* **5 Workflows** — CI, deploy, production deploy, database migrations, PR cleanup
* **Conductor scripts** — automated workspace creation per feature branch

GitHub Environments [#github-environments]

The deploy wizard creates three environments:

| Environment   | Branch        | Auto-deploy | Protection           |
| ------------- | ------------- | ----------- | -------------------- |
| `development` | `development` | Yes         | None                 |
| `preview`     | `preview`     | Yes         | None                 |
| `production`  | `main`        | Manual only | 2 reviewer approvals |

Each environment has its own set of secrets and variables, provisioned by the deploy wizard or manually via:

```bash
scripts/env/provision-github-env.sh development
scripts/env/provision-github-env.sh preview
```

Workflows [#workflows]

ci.yml — Pull Request Quality Gates [#ciyml--pull-request-quality-gates]

Triggers on PRs to `development`. Runs:

* Biome linting
* TypeScript typecheck
* Vitest unit tests
* Full build verification

All must pass before merge.

deploy-environment.yml — Dev & Preview Auto-Deploy [#deploy-environmentyml--dev--preview-auto-deploy]

Triggers on push to `development` or `preview`. Deploys all services in order:

1. Migrate databases (Drizzle schema push)
2. Push secrets to workers
3. Deploy Auth (others depend on it)
4. Deploy API + Metering (parallel)
5. Deploy Mastra (build, patch, Studio assets)
6. Deploy Web (Service Binding to Mastra)
7. Smoke tests (health checks on all services)

deploy-prd.yml — Manual Production Deploy [#deploy-prdyml--manual-production-deploy]

Triggered manually with inputs:

* **version** — git tag or commit SHA
* **run\_migrations** — whether to run DB migrations
* **confirm\_deploy** — must type "DEPLOY" to proceed

Requires 2 reviewer approvals via the `production` GitHub Environment.

db-migrate.yml — Standalone Database Migrations [#db-migrateyml--standalone-database-migrations]

For running Drizzle migrations outside of a deploy. Supports dry-run mode.

pr-cleanup.yml — Feature Branch Cleanup [#pr-cleanupyml--feature-branch-cleanup]

Triggers when a PR to `development` is closed. Deletes:

* Cloudflare Workers created by Conductor for that branch
* Turso database branches

Secrets & Variables [#secrets--variables]

Secrets (sensitive, stored encrypted) [#secrets-sensitive-stored-encrypted]

Pushed via `gh secret set --env <environment>`:

* Database URLs and tokens (AUTH, API, MASTRA, METERING)
* `BETTER_AUTH_SECRET`, `SESSION_SECRET`
* `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`
* `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
* `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`
* `CF_API_TOKEN`
* `RESEND_API_KEY`
* `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER`
* `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL`

Note: GitHub reserves the `GITHUB_*` prefix. GitHub OAuth credentials are stored as `OAUTH_GITHUB_CLIENT_ID` and `OAUTH_GITHUB_CLIENT_SECRET`.

Variables (non-sensitive, visible in logs) [#variables-non-sensitive-visible-in-logs]

Pushed via `gh variable set --env <environment>`:

* `CF_ACCOUNT_ID`, `CF_GATEWAY_ID`
* `STRIPE_PUBLISHABLE_KEY`
* `STRIPE_PRO_PRICE_ID`, `STRIPE_ENTERPRISE_PRICE_ID`
* `TRIAL_DAYS_PRO`, `TRIAL_DAYS_ENTERPRISE`
* `GOOGLE_PLACES_API_KEY`

Conductor Workspace Automation [#conductor-workspace-automation]

Conductor automates per-branch deployments. When you create a feature branch:

Setup (scripts/conductor/setup.sh) [#setup-scriptsconductorsetupsh]

1. Derives a slug from the branch name (e.g., `feat/MAK-33-settings` becomes `feat-mak-33-settings`)
2. Branches Turso databases from development (each feature gets isolated data)
3. Saves database URLs and tokens for the deploy step
4. Updates Linear issue to "In Progress" (if `LINEAR_API_KEY` is set)

Deploy (scripts/conductor/deploy.sh) [#deploy-scriptsconductordeploysh]

1. On first deploy: pushes all secrets to the new workers
2. Deploys services in dependency order (Auth first, then API/Metering, then Mastra/Web)
3. On subsequent deploys: only redeploys changed services (incremental)
4. Creates a per-workspace Stripe webhook

Services are available at: `https://{service}-{slug}.mastrakit.dev`

Archive (scripts/conductor/archive.sh) [#archive-scriptsconductorarchivesh]

On workspace deletion:

1. Deletes Stripe webhook
2. Deletes all Cloudflare Workers
3. Deletes Turso database branches
4. Updates Linear issue to "Done"

Branch Strategy [#branch-strategy]

```
feature/* ──PR──> development ──merge──> preview ──merge──> main
                      │                     │                 │
                  auto-deploy          auto-deploy      manual deploy
                  dev-*.domain        preview-*.domain   *.domain
```

Feature branches deploy via Conductor. `development` and `preview` auto-deploy via GitHub Actions. `main` (production) requires manual trigger with approval.

Environment File Management [#environment-file-management]

The `scripts/env/` directory contains:

| File                           | Purpose                                                      |
| ------------------------------ | ------------------------------------------------------------ |
| `.env.dev-secrets.example`     | Template with all keys (empty values)                        |
| `.env.dev-secrets`             | Your actual secrets (gitignored, populated by deploy wizard) |
| `.env.preview-secrets.example` | Template for preview environment                             |
| `.env.preview-secrets`         | Preview secrets (gitignored)                                 |
| `setup-dev-secrets.sh`         | Push secrets to per-developer Cloudflare Workers             |
| `setup-preview-secrets.sh`     | Push secrets to preview Workers                              |
| `provision-github-env.sh`      | Push secrets to GitHub Environments                          |

Provisioning Flow [#provisioning-flow]

```
.env.dev-secrets (local file)
    │
    ├── setup-dev-secrets.sh ──> Cloudflare Workers (per developer)
    │
    └── provision-github-env.sh ──> GitHub Environment secrets/variables
                                        │
                                        └── deploy-environment.yml ──> Workers (CI/CD)
```