GitHub Actions: PR Preview Environments
- Applies to
- Gatewayruntime for API, AI, and MCP gateways
- Hosting
- Managed EdgeManaged DedicatedSelf-HostedDiffers
1 difference by hosting option
Add --self-hosted-endpoint with your management API hostname to each zuplo deploy and zuplo delete command so it targets your cluster. See zuplo deploy.
Give every pull request its own Zuplo environment. Reviewers can test changes against a live API, and environments clean up automatically when PRs close.
Pass --branch on pull_request events
Workflows triggered by pull_request check out the pull request merge ref
(refs/pull/<number>/merge), not your branch. Without --branch, the Zuplo CLI
derives the environment name from that ref and creates an environment named
pull/<number>/merge instead of one named after your branch. If anything else
deploys the same branch — a push-triggered workflow, the GitHub integration,
or a local zuplo deploy — you end up with two environments and two different
URLs for the same branch. Always pass --branch with the source branch name
(github.head_ref).
.github/workflows/pr-workflow.yaml
This workflow:
- On PR open/update: Deploys to an environment named after the branch, runs tests, and comments the URL on the PR
- On PR close: Deletes the preview environment by branch name, so the cleanup job doesn't need the environment URL
How It Works
- The deploy step passes
--branchwith the PR's source branch name (github.head_ref), so the environment is named after the branch — the same name the GitHub integration would use - Each push to the PR updates the same environment, so the environment URL stays stable for the life of the branch
- Closing the PR (merge or abandon) triggers cleanup.
zuplo delete --branchtakes the same branch name the deploy step used and removes that branch's environment. If the environment is already gone, the command exits without an error - The PR comment lets reviewers quickly access the preview
A stable environment URL matters whenever an external system references it exactly — an OIDC token audience, a webhook registration, or an IP/URL allowlist. Capture the URL from the deploy output 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).
Next Steps
- Add automatic cleanup on branch delete as a backup
- Implement multi-stage deployment for production releases