Copy page

Deploy from CI/CD

Deploy from GitLab CI

Prerequisites: a running Workload, its service instance id, the deploy token, and zaroz-deploy.sh committed as deploy/zaroz-deploy.sh.

Variables

In Settings > CI/CD > Variables:

Key	Settings
ZAROZ_TOKEN	the zaroz_... token. Masked and Protected, so only pipelines on protected branches (main) can read it
ZAROZ_SERVICE	the service instance UUID
CI_DEPLOY_USER, CI_DEPLOY_PASSWORD	only for a private image. Create a deploy token with only read_registry (Settings > Repository > Deploy tokens) and GitLab fills these two variables for jobs automatically when its name is gitlab+deploy-token

The pipeline

Code
# .gitlab-ci.yml
stages: [build, deploy]

variables:
  IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA   # one immutable tag per commit

build:
  stage: build
  image: docker:27
  services: [docker:27-dind]
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
    - docker build -t "$IMAGE" .
    - docker push "$IMAGE"

deploy:
  stage: deploy
  image: alpine:3.20
  needs: [build]
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  # Never two deployments at once, and never an older commit over a newer one.
  resource_group: production
  environment: production
  before_script:
    - apk add --no-cache curl jq
  script:
    - sh deploy/zaroz-deploy.sh
  variables:
    # ZAROZ_TOKEN and ZAROZ_SERVICE: Settings > CI/CD > Variables
    # (ZAROZ_TOKEN masked and protected). A private registry also needs these two,
    # for a deploy token with read_registry:
    REGISTRY_USERNAME: $CI_DEPLOY_USER
    REGISTRY_PASSWORD: $CI_DEPLOY_PASSWORD

How it behaves:

• resource_group: production makes GitLab run one deploy job at a time and keep them in order, so an older commit never lands on top of a newer one.
• needs: [build] starts the deploy the moment the image is pushed.
• The deploy job fails when the rollout fails, after putting the previous image back. The environment: production entry gives you a deployment history in GitLab beside Zaroz's.
• Add when: manual to the deploy job's rules for a push-button production deploy.

Roll back

In Deploy > Environments > production, press the rollback button on an older deployment: GitLab re-runs that commit's deploy job, which deploys that commit's image. By hand: IMAGE=$CI_REGISTRY_IMAGE:<old sha> sh deploy/zaroz-deploy.sh.

Self-managed GitLab

Nothing changes except the registry host, which is already in CI_REGISTRY_IMAGE. Zaroz pulls the image from inside its cluster, so the registry must be reachable from the internet (or allow Zaroz's egress addresses).