Zuplo CLI: Deploy

Common use cases

The following examples assume that you are passing in your --api-key either as an argument or through the ZUPLO_API_KEY environment variable.

Deploying your gateway

Code
# The following will use the current Git branch as the name of the environment

git checkout -b my-new-branch
zuplo deploy --project my-project

Code
# If you don't wish to use the current Git branch as the name of the
# environment, you can specify one using --environment

zuplo deploy --project my-project --environment my-env-name

Deploying from CI/CD

Without --environment, the CLI names the environment after the current git branch. CI systems usually check out a detached HEAD, in which case the CLI resolves the branch from the remote branches that contain the checked-out commit. Two cases break this inference:

• On GitHub Actions pull_request events, the checkout is the pull request merge ref (refs/pull/<number>/merge) — a commit that doesn't exist on any branch — so the environment is named after that ref instead of your branch.
• When the checked-out commit exists on more than one branch, the first match wins, which may not be the branch that triggered the build.

Always pass --environment explicitly in CI so that every trigger deploys the same, predictably named environment:

Code
# GitHub Actions: github.head_ref is the source branch on pull_request
# events; github.ref_name is the branch on push events
zuplo deploy --project my-project --environment "$BRANCH_NAME"

Deploying the same environment name always updates the same environment and keeps its URL stable across deploys. This matters whenever an external system must match the URL exactly — an OIDC token audience, a webhook registration, or an allowlist. Capture the URL from the deploy output (Deployed to https://...) rather than constructing it from the branch name: the URL hostname uses a normalized, truncated form of the environment name plus a unique identifier. See Branch-Based Deployments for the naming rules.

Polling timeout

By default, the deploy command polls the status of the deployment every second for up to 250 attempts (a little over four minutes). For most deployments this is enough time for the build and deploy process to complete. However, if you have a large project, this may not be enough time. You can increase the timeout by setting the following environment variables.

• POLL_INTERVAL - The interval in milliseconds between each poll. Default is 1000 (1 second).
• MAX_POLL_RETRIES - The maximum number of polls before the command times out. Default is 250.

The following example polls every 5 seconds for up to 300 attempts (25 minutes).

Code
POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy

Note, that even if the CLI times out, the deployment will continue. You can check the status of the deployment in your project in the Zuplo Portal.

Examples

Options