Automate
Deploy from CI
Roll out every build automatically: deploy hooks, the GitHub Action, GitHub Actions and GitLab CI examples, and why to deploy commit SHAs.
QuickTane doesn't build your code: your CI builds the image, pushes it to a registry, and then tells QuickTane to roll out the new tag. That last step is one HTTP call. There are two ways to make it:
- A deploy hook — a secret URL per service. Nothing else to set up, works from any CI. It can only deploy a new tag of the image the service already runs.
- An API key with only the
services:deployscope — for the official GitHub Action, or when one pipeline deploys several services. See the REST API.
Create a deploy hook #
- Open the service in the dashboard, go to Settings → Deploy from CI and click Create deploy hook.
- Copy the URL. It is shown once: QuickTane stores only a hash of it.
- Save it as a secret in your CI, e.g.
QUICKTANE_DEPLOY_HOOK. Never commit it — whoever has the URL can deploy the service.
Lost the URL, or it leaked? Rotate it: you get a new URL and the old one stops working at once. Revoke removes the hook. Anyone who may change the service can manage its hook; the card shows when it was last called and what happened.
Calling the hook #
Send a POST with the new tag — in a JSON body, a form body or the query string:
curl -fsS -X POST "$QUICKTANE_DEPLOY_HOOK" \
-H "Content-Type: application/json" \
-d "{\"tag\": \"$GIT_SHA\"}"
- With a
tag: the service's current repository at that tag is checked in the registry, pinned to its digest and rolled out — exactly likePOST /v1/services/{id}/deploywithtag. A hook can't switch the service to another repository or registry: animageparameter is refused. Change the image in the dashboard or with the API. - Without a tag: the current reference is pulled again (the dashboard's Redeploy). If the tag moved, its new digest is rolled out; if not, the service restarts.
- Sending the tag that is already deployed changes nothing — the pinned digest is kept. Deploy a unique tag per build.
The response is 202 Accepted: the image was found and the rollout is queued. It contains deploy_fingerprint and status_url, which the hook's token also opens. Poll it until applied_fingerprint equals the fingerprint and is_ready is true:
RESPONSE=$(curl -fsS -X POST "$QUICKTANE_DEPLOY_HOOK" \
-H "Content-Type: application/json" \
-d "{\"tag\": \"$GIT_SHA\"}")
FINGERPRINT=$(echo "$RESPONSE" | jq -r .deploy_fingerprint)
STATUS_URL=$(echo "$RESPONSE" | jq -r .status_url)
for i in $(seq 1 60); do
STATUS=$(curl -fsS "$STATUS_URL")
if [ "$(echo "$STATUS" | jq -r .status)" = "failed" ]; then
echo "$STATUS" | jq -r .status_reason; exit 1
fi
if [ "$(echo "$STATUS" | jq -r .applied_fingerprint)" = "$FINGERPRINT" ] \
&& [ "$(echo "$STATUS" | jq -r .is_ready)" = "true" ]; then
echo "Deployed"; exit 0
fi
sleep 5
done
echo "Timed out"; exit 1
| Status | Meaning |
|---|---|
202 | Accepted — the rollout is queued. |
403 | The team is suspended, or its subscription ended — the same refusals as the API. |
404 | Unknown, rotated or revoked hook URL. |
422 | Refused, and nothing changes: an invalid tag or an image parameter, an image the registry can't provide, or a stopped service (start it first). Without a tag, also while the previous deploy is still rolling out; a new tag is accepted then and replaces it. message says why. |
429 | More than 10 calls per hook and minute, or too many wrong hook URLs from your IP; wait for Retry-After seconds. |
GitHub Actions #
Build the image, push it to the GitHub Container Registry tagged with the commit SHA, then deploy that tag. Store the hook URL as the repository secret QUICKTANE_DEPLOY_HOOK:
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
with:
push: true
platforms: linux/amd64
tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
- name: Deploy to QuickTane
run: |
curl -fsS -X POST "$QUICKTANE_DEPLOY_HOOK" \
-H "Content-Type: application/json" \
-d "{\"tag\": \"$GITHUB_SHA\"}"
env:
QUICKTANE_DEPLOY_HOOK: ${{ secrets.QUICKTANE_DEPLOY_HOOK }}
The service must already run an image from the same repository (ghcr.io/your-org/your-repo) — create it once in the dashboard with the first tag. GHCR repository names are lower-case: if your GitHub owner or repository name has capitals, write the image name in lower case.
The QuickTane GitHub Action #
The official action deploys with an API key and waits until the new version is live (or fails the job with the reason). Create a key with only the services:deploy scope under API keys and store it as QUICKTANE_API_KEY; then the last step of the workflow above becomes:
- uses: quicktane/deploy@v1
with:
api-key: ${{ secrets.QUICKTANE_API_KEY }}
service: 42 # the id from the dashboard URL /services/42
tag: ${{ github.sha }}
Use the service's numeric id — it's in the dashboard URL, /services/<id>. A key with only services:deploy can deploy to an id and wait for the rollout. The action also accepts the service's slug (plus project when the slug exists in several projects), but looking a slug up needs a key that also has services:read.
Instead of tag it takes a full image. wait (default on) and timeout (seconds) control the waiting. Its outputs are service-id, deploy-fingerprint, url and status.
GitLab CI #
Push to the project's GitLab container registry and call the hook. Store the hook URL as a masked CI/CD variable QUICKTANE_DEPLOY_HOOK:
deploy:
stage: deploy
image: docker:27
services: [docker:27-dind]
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
- docker build --platform linux/amd64 -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" .
- docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
- apk add --no-cache curl
- >
curl -fsS -X POST "$QUICKTANE_DEPLOY_HOOK"
-H "Content-Type: application/json"
-d "{\"tag\": \"$CI_COMMIT_SHA\"}"
With an API key instead #
From any CI, an API key with only services:deploy can deploy a tag (or a whole new image) to a service by its id and poll its status:
curl -fsS -X POST https://api.quicktane.com/v1/services/42/deploy \
-H "Authorization: Bearer $QUICKTANE_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"tag\": \"$GIT_SHA\"}"
The full polling loop and every endpoint are in REST API → Deploy from CI.
Deploy unique tags, not latest
#
Tag every build with something unique — the commit SHA is the easiest — and deploy that tag:
- It actually deploys. Sending a tag that is already deployed keeps the pinned digest, so pushing a new
latestand deployinglatestagain does nothing. (Calling the hook without a tag does re-pull a moved tag, but then you can't tell which build is live.) - You know what runs. The dashboard and the API show the tag and its digest; a SHA points straight at the commit.
- Rolling back is deploying the previous SHA.
Private images #
Images pushed to GHCR are private by default, and so is a private GitLab project's registry. Either make the package public, or add read-only registry credentials to the service's project before the first deploy — otherwise the deploy is refused with Image not found or no access. Deploy hooks and API keys use those credentials automatically.
Something missing or wrong? Tell us — or open a ticket from the dashboard.