Deploy from CI with one command and one key
Deploy to production from GitHub Actions using one secret key and the vibiz deploy command, with automatic content hashing and built-in rollbacks.
On this page 9 sections
- Authenticating GitHub Actions with a single key
- Configuring the GitHub Actions production workflow
- Pull request previews and promoting to production
- How content hashing and upload limits work
- Inspecting versions and diffs in your pipeline
- Automating rollbacks and Mission Control health checks
- Exporting project snapshots from CI
- Next steps
- FAQ
To deploy from GitHub Actions using the CLI, store your API key as a secret named VIBIZ_API_KEY and run npx @vibiz/cli deploy. The CLI reads your credentials directly from the environment, packages your project files, uploads only modified content, and triggers the build. You get a live deployment at https://<slug>.vibiz.app or your connected domain without maintaining separate deployment configuration files.
Automating deploys from continuous integration keeps shipping predictable. Because the CLI and the underlying API use the same authentication format, your pipeline requires only one secret to manage previews, production releases, version tracking, and health checks.
Authenticating GitHub Actions with a single key
The CLI checks your runner environment for VIBIZ_API_KEY before looking at local configuration files. On your laptop, vibiz login writes credentials to ~/.vibiz/config.json. In GitHub Actions, setting the secret in your workflow environment overrides this cleanly.
You can use either an account key or a project key (vz_sk_...). Account owners can choose between two key permission tiers:
- Full access: Can perform all administrative actions, manage domains, and read production secrets.
- Limited: Can deploy code, build preview releases, and run health checks, but cannot read production secrets or move live money.
For standard CI/CD deployment pipelines, a Limited key gives the runner everything it needs to build and deploy applications safely without exposing live environment secrets.
Your repository identifies the correct target through ./vibiz.json, which vibiz init generates when you create the project. If you deploy multiple applications from one repository or prefer not to commit vibiz.json, pass the project identifier explicitly using the --project flag:
vibiz deploy --project prj_123Configuring the GitHub Actions production workflow
To create a production pipeline, add your key to your GitHub repository under Settings ▸ Secrets and variables ▸ Actions as VIBIZ_API_KEY.
Then create a workflow file at .github/workflows/deploy.yml:
name: Deploy
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: Deploy to production
env:
VIBIZ_API_KEY: ${{ secrets.VIBIZ_API_KEY }}
run: npx @vibiz/cli deploy -m "GitHub Actions: ${{ github.sha }}"When you push to main, the runner executes vibiz deploy. The -m flag tags the deployment message in your version history. If you deploy a built subfolder instead of the repository root, specify that directory directly:
- name: Deploy subdirectory
env:
VIBIZ_API_KEY: ${{ secrets.VIBIZ_API_KEY }}
run: npx @vibiz/cli deploy ./dist -m "Build ${{ github.run_number }}"For more details on static files or full-stack setups, see our guides on how to deploy a static site with one command and how to deploy a Next.js app with a database and sign-in in one command. If you are budgeting infrastructure for new projects, you can also review the cheapest way to host a website and database for a side project.
Pull request previews and promoting to production
You can preview incoming changes without overwriting your live website. Adding --preview to the deploy command builds your code at a separate, isolated URL.
Here is a workflow that builds previews for pull requests targeting main:
name: Preview Deployment
on:
pull_request:
branches:
- main
jobs:
preview:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: Build preview
env:
VIBIZ_API_KEY: ${{ secrets.VIBIZ_API_KEY }}
run: npx @vibiz/cli deploy --preview -m "PR #${{ github.event.pull_request.number }}"A preview deployment does not touch the active production site. If you decide to promote that specific preview to production later from your terminal or another script, run the promote command:
vibiz promote dep_123When promoted, a preview deployment is rebuilt as production. Existing production deployments switch instantly without rebuilding.
How content hashing and upload limits work
When the CLI runs inside your workflow, it calculates the content hash of every file in the directory. Files that the platform already holds are skipped, which keeps uploads minimal.
Certain directories and files are ignored automatically by the CLI. You do not need to configure an ignore file for common build outputs or secrets. The CLI refuses to upload:
node_modules.git.nextdist.turbovibiz.json.env*files- Sensitive credential files (
*.pem,id_rsa,.npmrc)
Here are the specifications and operational boundaries for builds and deployments:
| Metric | Limit / Detail |
|---|---|
| Daily builds per project | 30 builds per UTC day (exceeding returns 429 rate_limited) |
| Maximum files per deployment | 10,000 files |
| Maximum individual file size | 50 MB |
| Hosting price | $0 recorded in usage (pricing not decided) |
| Rollback speed | Instant for production builds cached on the host |
You can check how many builds your project has performed today by running GET /v1/usage, which includes builds_today. For complete details on hosting mechanics, visit the Hosting documentation.
Inspecting versions and diffs in your pipeline
Every deployment creates a permanent version entry you can inspect and compare. You can list previous versions or compare changes between builds directly from the command line:
vibiz versions # newest first: message, who, when, live, files changed
vibiz diff # the live version against the one beforeFile counts and diffs are calculated against the newest working version before it. A diff details each file added, updated, or deleted, showing a unified diff for text files and byte sizes for binary files. Text files up to 512 KB are compared, up to 100 files and 200 KB of total changes at a time. If changes exceed these bounds, truncated is true and each file includes a note describing what was left out.
Versions have no time limit and are not deleted as long as the project exists. Files are stored by content hash outside the hosting layer, so you can inspect historical code changes at any time.
Automating rollbacks and Mission Control health checks
After the deploy command finishes, you can verify that the live application responds properly by querying Mission Control and health checks.
The CLI provides commands to inspect application health immediately:
- name: Verify application status
env:
VIBIZ_API_KEY: ${{ secrets.VIBIZ_API_KEY }}
run: |
npx @vibiz/cli status
npx @vibiz/cli health --failingMission Control monitors several health checks in the background:
- Site up: Verifies that your production address answers without 5xx errors or timeouts, resolves correctly, and serves valid HTTPS certificates.
- Last deploy: Flags if the latest production deploy failed or has been queued for over 30 minutes.
- Resources: Verifies that provisioned resources (database, sign-in, email) are healthy.
- Limits: Warns if a project build cap or AI budget reaches 80%, and fails when the cap is reached.
If an automated test fails inside your pipeline or the site fails health checks, you can revert instantly to the previous production deployment:
vibiz rollbackvibiz rollback points traffic back to the version before the live one. An instant switch runs with the environment variables that version was built with. The database is not rolled back: rows and schema migrations stay as they are, so rollback only reverts frontend and server code.
Exporting project snapshots from CI
If your CI workflow needs to back up code or data on a schedule, you can create full exports using the CLI. The Export resource bundles code and database snapshots:
vibiz export --code -o backup.zipTo back up the development database along with the code guide, pass the relevant flags:
vibiz export --db --csvProduction database exports and raw secret values require a Full access key (owner_only). When using a Limited key inside GitHub Actions, vibiz export defaults to the development environment, keeping production data separated from automated build workers.
Next steps
Add VIBIZ_API_KEY to your repository settings and drop the workflow YAML into .github/workflows/deploy.yml to automate your releases. To learn more about initializing resources or configuring local environments, read the Quickstart guide.
Frequently asked questions
Can I use a Limited access API key in GitHub Actions?
Yes. A Limited key can package code, build previews, and deploy production sites, while preventing the runner from viewing production database secrets or moving live funds.
What happens if my GitHub Actions workflow exceeds the daily build limit?
Projects are limited to 30 builds per UTC day. If you exceed this limit, the CLI receives an HTTP 429 `rate_limited` error with a reset timestamp in `details.resets_at`.
Does running vibiz rollback in CI also roll back database migrations?
No. Rolling back switches your live application code and static assets back to the prior deployment, but database tables and rows remain in their current state.
Do I need to manually upload unchanged static files on every build?
No. Deployments calculate content hashes for each file, and files that the host already stores are never uploaded twice.