deplo.ai/docs

CI Usage

Run deplo deploy --yes in a pipeline with a DEPLO_TOKEN secret and the exit code gates the rest of your workflow — the full deployment log, including the AI diagnosis on failure, lands in your CI output.

Do you need the CLI in CI?
Once a repository has deployed, the platform's GitHub webhook redeploys it automatically on every push — no CI required. Use the CLI in CI when you want more than fire-and-forget: run tests first, make the pipeline wait for the deployment and fail when it fails, and keep the deploy log next to your build log. The two compose fine; a CLI-triggered deploy is just a deploy.

Setup#

  1. Create a dedicated CLI token

    At deplo.in → Settings → CLI tokens, create a token named for the pipeline (for example github-actions). A dedicated token can be revoked without signing your laptop out, and its lastUsedAt in Settings tells you the pipeline is actually using it. The token is shown once — copy it now.

  2. Store it as a CI secret

    In GitHub: repository → Settings → Secrets and variables → Actions → New repository secret, named DEPLO_TOKEN. Never commit the token; the DEPLO_TOKEN environment variable overrides the config file precisely so nothing needs to be written to disk in CI (see Configuration).

  3. Run the deploy

    bash
    npx @deplo.ai/cli deploy --yes

    --yes skips the confirmation prompt. In CI there is no TTY, so the CLI never prompts anyway — missing prerequisites become errors with clear messages instead of interactive questions, for example ✗ not signed in — run deplo login (or set DEPLO_TOKEN) or ✗ vercel is not connected — run deplo connect vercel.

Environment variables must exist before CI deploys#

Interactively, deplo prompts for required environment variables when a deployment pauses on WAITING_FOR_ENV. In CI it cannot prompt — the run fails pointing at the dashboard URL where the variables can be provided. Do the first deploy of a repository from the dashboard or your terminal so all required variables are captured; CI redeploys reuse them. See Environment Variables.

GitHub Actions workflow#

.github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run tests
        run: npm ci && npm test

      - name: Deploy with deplo
        run: npx @deplo.ai/cli deploy --yes
        env:
          DEPLO_TOKEN: ${{ secrets.DEPLO_TOKEN }}

The checkout step is only there for your tests — deplo deploys from the repository on GitHub, not from the runner's working copy, using the origin remote that actions/checkout sets up. Make sure unpushed commits are not what you expect to ship.

Exit codes gate the pipeline#

Exit codeMeaning
0Deployment completed — both URLs live.
1Anything else: deployment failed or was cancelled, missing token or provider connection, repo not visible, network error.

Because deploy follows the deployment to a terminal state before exiting, any step placed after it (smoke tests, notifications) runs against the live URLs — or not at all. The full log streams into the CI output as it happens, and on failure the last lines include the error plus a pointer to the dashboard's full log and AI diagnosis:

failed run (CI log)
  Deploying backend to Render…
  error: build failed — Cannot find module 'express'
  AI diagnosis: express is imported in server/src/index.ts but missing from dependencies

✗ Deployment failed — build failed
  full log + AI diagnosis: deplo.in/dashboard/deployments/dep_8f31a2

Roadmap#

v0.2 A --json output mode for machine-readable results (URLs, deployment id, status) so pipelines can stop parsing human-oriented text.