Skip to content

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:deploy scope — for the official GitHub Action, or when one pipeline deploys several services. See the REST API.

Create a deploy hook #

  1. Open the service in the dashboard, go to Settings → Deploy from CI and click Create deploy hook.
  2. Copy the URL. It is shown once: QuickTane stores only a hash of it.
  3. 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:

bash
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 like POST /v1/services/{id}/deploy with tag. A hook can't switch the service to another repository or registry: an image parameter 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:

bash
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
StatusMeaning
202Accepted — the rollout is queued.
403The team is suspended, or its subscription ended — the same refusals as the API.
404Unknown, rotated or revoked hook URL.
422Refused, 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.
429More 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:

.github/workflows/deploy.yml
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:

.github/workflows/deploy.yml
- 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:

.gitlab-ci.yml
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:

bash
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 latest and deploying latest again 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.