fix: make CI environment sync explicit

Author: devalade

.agent/skills/shipnode/REFERENCE.md

@@ -77,8 +77,8 @@ Most commands accept `--config <path>` and `--app <name>` (multi-app). `rollback
 ### CI/CD
 | Command | Description |
 |---|---|
-| `ci github` | Write `.github/workflows/shipnode-deploy.yml` |
-| `ci env-sync [--all]` | Push .env → GitHub repo secrets |
+| `ci github [--app name] [--environment name] [--sync-env]` | Write the deploy workflow; app env stays server-managed unless opted in |
+| `ci env-sync [--app name] [--environment name] [--file path] [--dry-run] [--all]` | Store one complete dotenv file as a GitHub Environment secret |
 
 ### Config
 | Command | Description |

.agent/skills/shipnode/SKILL.md

@@ -90,6 +90,10 @@ Target one app: `shipnode deploy --app api`, `shipnode logs --app web`. `rollbac
 3. `shipnode env` (per app if multi-app: `--app api`)
 4. `shipnode deploy`
 
+### CI/CD
+
+Runtime env stays on the VPS by default: upload it with `shipnode env`, then generate a code-only workflow with `shipnode ci github`. To opt one app into GitHub-managed env, run `shipnode ci env-sync --app api --environment production`, then generate with the matching `--app api --environment production --sync-env` flags. Shipnode stores the complete dotenv file as one Environment secret and uploads it with `--no-reload` immediately before deployment.
+
 ### Releases
 Every deploy uses release dirs + atomic `current` symlink. Failed deploys revert `current` (when a previous release exists) and record `status: 'failed'`.
 

.claude/skills/shipnode/REFERENCE.md

@@ -77,8 +77,8 @@ Most commands accept `--config <path>` and `--app <name>` (multi-app). `rollback
 ### CI/CD
 | Command | Description |
 |---|---|
-| `ci github` | Write `.github/workflows/shipnode-deploy.yml` |
-| `ci env-sync [--all]` | Push .env → GitHub repo secrets |
+| `ci github [--app name] [--environment name] [--sync-env]` | Write the deploy workflow; app env stays server-managed unless opted in |
+| `ci env-sync [--app name] [--environment name] [--file path] [--dry-run] [--all]` | Store one complete dotenv file as a GitHub Environment secret |
 
 ### Config
 | Command | Description |

.claude/skills/shipnode/SKILL.md

@@ -90,6 +90,10 @@ Target one app: `shipnode deploy --app api`, `shipnode logs --app web`. `rollbac
 3. `shipnode env` (per app if multi-app: `--app api`)
 4. `shipnode deploy`
 
+### CI/CD
+
+Runtime env stays on the VPS by default: upload it with `shipnode env`, then generate a code-only workflow with `shipnode ci github`. To opt one app into GitHub-managed env, run `shipnode ci env-sync --app api --environment production`, then generate with the matching `--app api --environment production --sync-env` flags. Shipnode stores the complete dotenv file as one Environment secret and uploads it with `--no-reload` immediately before deployment.
+
 ### Releases
 Every deploy uses release dirs + atomic `current` symlink. Failed deploys revert `current` (when a previous release exists) and record `status: 'failed'`.
 

README.md

@@ -425,10 +425,16 @@ Falls back to installing `cloudflared` from the upstream GitHub `.deb` if `pkg.c
 ### CI/CD
 
 ```bash
-shipnode ci github             # Generate .github/workflows/shipnode-deploy.yml
-shipnode ci env-sync           # Push .env vars to GitHub repository secrets
+shipnode ci github             # Generate a server-managed-env deploy workflow
+shipnode env --app api         # Upload runtime env directly to the VPS (default)
+
+# Opt in to GitHub-managed env for one app/environment
+shipnode ci env-sync --app api --environment production --all
+shipnode ci github --app api --environment production --sync-env
 ```
 
+The default workflow deploys code without copying application secrets through GitHub. With `--sync-env`, Shipnode stores the complete dotenv file as one GitHub Environment secret, uploads it with `--no-reload`, deploys, then removes the runner copy. Production and staging use distinct environments and secret names.
+
 ### Configuration
 
 ```bash

docs/adr/0006-ci-environment-ownership.md

@@ -0,0 +1,32 @@
+# Keep runtime env on the VPS by default; make GitHub ownership explicit
+
+Shipnode deployments need application configuration during remote backend builds and process startup. Static frontend builds may need the same configuration on the CI runner. Treating every dotenv key as an independent repository secret created partial-update risks, lost dotenv syntax, secret-name collisions between apps, and a workflow that did not actually consume the synchronized values.
+
+## Decision
+
+Runtime env remains server-managed by default. Operators upload it directly with `shipnode env`; ordinary generated workflows deploy code without transferring application secrets through GitHub.
+
+GitHub-managed env is an explicit per-app, per-environment mode:
+
+- `ci env-sync` stores the complete dotenv file as one GitHub Environment secret named `SHIPNODE_ENV_<ENVIRONMENT>_<APP>`.
+- The secret value is sent to `gh secret set` over standard input, never as a process argument.
+- `ci github --sync-env` requires an app target in multi-app workspaces and generates a job bound to the selected GitHub Environment.
+- The workflow rejects a missing secret, materializes the configured file under a restrictive umask, uploads it with `shipnode env --no-reload`, deploys the app, and removes the runner copy with `if: always()`.
+- Files larger than GitHub's 48 KB secret limit are rejected before invoking GitHub.
+
+SSH host, user, and port stay in committed Shipnode configuration. CI secrets are limited to the SSH private key, a trusted known-hosts entry, and the optional app environment blob.
+
+## Deployment behavior
+
+Uploading with `--no-reload` is required for release safety. A running old process retains its existing process environment while the new blue-green colour starts with the newly uploaded shared env. Health checks and the Caddy switch still decide whether the release goes live.
+
+Generated workflows do not run a generic repository-root build. Frontend strategies already build locally during `shipnode deploy`, while backend strategies build remotely after sourcing the shared env. The workflow only installs dependencies needed to load project configuration and execute Shipnode.
+
+Production jobs use GitHub Environment protection, least-privilege repository permissions, a timeout, and serialized concurrency with `cancel-in-progress: false`. Root-level monorepo changes continue to trigger deployments; no `paths` filter is generated.
+
+## Trade-offs
+
+- Server-managed env minimizes secret exposure but requires an out-of-band env upload or rotation step.
+- GitHub-managed env makes CI reproducible but exposes the complete application environment to GitHub and its ephemeral runner.
+- One opaque secret provides atomic file replacement and exact dotenv preservation, but GitHub cannot rotate or audit individual keys independently.
+- Environments larger than 48 KB need to remain server-managed or move to an external secret manager; Shipnode does not introduce an encrypted-file format.