CI/CD
Deploy hooks
Deploy hooks are unique URLs that trigger a deployment when called with an HTTP POST. They let you deploy from any external system, a GitHub Actions workflow, a GitLab pipeline, a Jenkins job, a custom script, or even a cURL command in a terminal.
Unlike auto-deploy (which reacts to a git push), deploy hooks give you explicit control. Use them when you want to run tests or build artifacts first, then deploy only after upstream checks pass.
Response from a hook call
{
"deploymentId": "dep_9xk2mq7rz",
"service": "api-service",
"status": "queued",
"branch": "main",
"dashboardUrl": "https://app.stackblaze.cloud/deploys/dep_9xk2mq7rz"
}
How it flows
Step by step
Generate a deploy hook URL
Open your service in the StackBlaze dashboard, go to Settings → Deploy Hooks, and click "Generate Hook URL". Each service can have multiple hook URLs, one per external system if you prefer.
Treat the URL like an API key
The hook URL contains a secret token embedded in the path. Anyone who holds it can trigger a deploy. Store it in your CI secret store (GitHub Actions Secrets, GitLab CI Variables, etc.) and never commit it to your repo.
Trigger a deploy with a POST request
Send an HTTP POST to the hook URL from your CI pipeline, a script, or any tool that speaks HTTP. No body is required, StackBlaze reads all configuration from the service settings.
# Trigger a deploy
curl -X POST \
https://api.stackblaze.cloud/deploy-hooks/abc123def456
Pass optional query parameters
Append query params to control the deploy: ?branch=feat/new-ui deploys a specific branch, ?clear_cache=true invalidates the build cache. Both can be combined.
# Deploy a specific branch and clear cache
curl -X POST \
"https://api.stackblaze.cloud/deploy-hooks/abc123?branch=main&clear_cache=true"
Poll the deployment status
The POST response includes a deployment ID. Use it to check progress by calling the deployments API. Most teams poll every 5 seconds until the status is "succeeded" or "failed".
# Response from the hook call
{
"deploymentId": "dep_9xk2mq7",
"status": "queued"
}
# Poll for completion
curl https://api.stackblaze.cloud/deployments/dep_9xk2mq7
CI integration examples
# .github/workflows/deploy.yml
name: Deploy to StackBlaze
on:
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Trigger StackBlaze deploy
run: |
curl -X POST \
"${{ secrets.STACKBLAZE_DEPLOY_HOOK }}"
# .gitlab-ci.yml
deploy:
stage: deploy
script:
- curl -X POST "$STACKBLAZE_DEPLOY_HOOK"
only:
- main
Under the hood
Each deploy hook URL contains a service ID and a secret HMAC token. When StackBlaze receives a POST request it validates the token, then enqueues a Tekton PipelineRun for the target service. The HTTP response is returned immediately (202 Accepted), the build runs asynchronously.
- HMAC validation: the secret token is hashed with SHA-256. Requests without a valid token return 401 immediately, before any build work starts.
- Tekton PipelineRun: StackBlaze creates a Tekton PipelineRun resource in the build namespace. Tekton clones the repo, runs the build steps, pushes the image to the container registry, and then patches the Deployment's image tag.
- Async deploy ID: the deployment ID returned in the response maps 1-to-1 to the Tekton PipelineRun name, making it easy to query build logs from the API or dashboard.