CI/CD
Overview
Use Handoff with any CI/CD pipeline or deployment platform, from VPS to Vercel.
Handoff has two ways to deliver environment variables into your running app. Which one you pick depends on where the app runs.
- Inject at runtime with
handoff run. Wrap your app's start command. The CLI pulls secrets into memory and spawns the child with env vars set. Nothing is written to disk. Use this whenever you control the process. - Sync to the platform's env store from CI. For serverless platforms that own your app's lifecycle. A CI step runs
handoff pulland pushes the result into the platform's env API before triggering the deploy.
Rule of thumb
If you control the process that runs the app, use handoff run. If the platform owns the process, sync from CI before every deploy.
Pick your deployment target
| Target | Pattern | Guide |
|---|---|---|
| GitHub Actions (tests, build, deploy scripts) | handoff run or handoff pull inside the job | GitHub Actions |
| VPS, bare metal | handoff run as the systemd ExecStart | VPS with systemd |
| Docker image (self-built) | handoff run as the container CMD | Docker |
| Fly.io, Render, Railway, Heroku | Same as Docker: handoff run in your Dockerfile or buildpack | Docker |
| Kubernetes | handoff run in the image, token via a Secret | Kubernetes |
| Vercel, Netlify, Cloudflare Workers, AWS Lambda | Sync from CI into the platform's env store | Serverless |
First-time setup
Whatever target you pick, the starting point is the same: create a Handoff API token scoped to your pipeline, then store it as HANDOFF_TOKEN in your CI provider's secret manager or your platform's secret store. The CLI reads that env var automatically; no handoff login step needed on servers or runners.