Skip to main content

CI/CD Integration

Automate your deployments to SailOps using the Public API — with direct API calls or declarative Stack files.

SailOps offers two approaches for CI/CD integration:

ApproachBest ForHow It Works
Direct API callsSimple deployments (update image, restart)Call specific endpoints like PATCH /containers/{name}
Stack EngineFull infrastructure managementDefine everything in a YAML file and apply with one call

Both approaches use the same API key authentication. Store your API key as a CI/CD secret — never commit it to source control.

Prerequisites​

  • A SailOps project with an API key
  • A container registry accessible from SailOps (GHCR, GitLab Registry, Docker Hub, etc.)
  • Your API key stored as a CI/CD secret:
    • GitHub Actions: Settings > Secrets and variables > Actions > New repository secret → SAILOPS_API_KEY
    • GitLab CI: Settings > CI/CD > Variables → SAILOPS_API_KEY (masked)

Approach 1: Direct API Calls​

Use individual API endpoints to update specific resources. Best for simple workflows like "build image, update container."

PATCH vs PUT

Use PATCH /containers/{container} to update only the image (and optionally the init image) — all other settings are preserved. Use PUT only when you need to replace the entire container spec (resources, ports, probes, etc.). The examples below use PATCH for simplicity.

GitHub Actions — Deploy a Container​

# .github/workflows/deploy.yml
name: Build & Deploy

on:
push:
branches: [main]

env:
IMAGE: ghcr.io/${{ github.repository }}
CONTAINER_NAME: my-api

jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4

- name: Log in to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- name: Build and push image
uses: docker/build-push-action@v6
with:
push: true
tags: |
${{ env.IMAGE }}:${{ github.sha }}
${{ env.IMAGE }}:latest

- name: Deploy to SailOps
run: |
HTTP_CODE=$(curl -s -o /tmp/response.json -w "%{http_code}" -X PATCH \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{"image": "${{ env.IMAGE }}:${{ github.sha }}"}' \
https://app.sailops.io/api/public/api/v1/containers/${{ env.CONTAINER_NAME }})

if [ "$HTTP_CODE" -ge 400 ]; then
echo "Deploy failed with HTTP $HTTP_CODE:"
cat /tmp/response.json | jq .
exit 1
fi
echo "Deployed successfully"

- name: Restart container
run: |
curl -sf -X POST \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
https://app.sailops.io/api/public/api/v1/containers/${{ env.CONTAINER_NAME }}/restart

GitLab CI — Deploy a Container​

# .gitlab-ci.yml
stages:
- build
- deploy

variables:
IMAGE: $CI_REGISTRY_IMAGE
CONTAINER_NAME: my-api

build:
stage: build
image: docker:27
services:
- docker:27-dind
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
script:
- docker build -t $IMAGE:$CI_COMMIT_SHA -t $IMAGE:latest .
- docker push $IMAGE:$CI_COMMIT_SHA
- docker push $IMAGE:latest
rules:
- if: $CI_COMMIT_BRANCH == "main"

deploy:
stage: deploy
image: curlimages/curl:latest
script:
- |
HTTP_CODE=$(curl -s -o /tmp/response.json -w "%{http_code}" -X PATCH \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"image\": \"$IMAGE:$CI_COMMIT_SHA\"}" \
https://app.sailops.io/api/public/api/v1/containers/$CONTAINER_NAME)

if [ "$HTTP_CODE" -ge 400 ]; then
echo "Deploy failed with HTTP $HTTP_CODE:"
cat /tmp/response.json
exit 1
fi
echo "Deployed successfully"
- |
curl -sf -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
https://app.sailops.io/api/public/api/v1/containers/$CONTAINER_NAME/restart
rules:
- if: $CI_COMMIT_BRANCH == "main"
environment:
name: production

Multi-Container Deployment​

Deploy multiple containers from a monorepo by detecting which services changed:

GitHub Actions​

# .github/workflows/deploy-multi.yml
name: Deploy Services

on:
push:
branches: [main]
paths:
- 'services/**'

jobs:
detect-changes:
runs-on: ubuntu-latest
outputs:
api: ${{ steps.changes.outputs.api }}
worker: ${{ steps.changes.outputs.worker }}
steps:
- uses: actions/checkout@v4
- uses: dorny/paths-filter@v3
id: changes
with:
filters: |
api:
- 'services/api/**'
worker:
- 'services/worker/**'

deploy-api:
needs: detect-changes
if: needs.detect-changes.outputs.api == 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build and push
run: |
echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
docker build -t ghcr.io/${{ github.repository }}/api:${{ github.sha }} services/api/
docker push ghcr.io/${{ github.repository }}/api:${{ github.sha }}
- name: Deploy API
run: |
curl -sf -X PATCH \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{"image": "ghcr.io/${{ github.repository }}/api:${{ github.sha }}"}' \
https://app.sailops.io/api/public/api/v1/containers/api

deploy-worker:
needs: detect-changes
if: needs.detect-changes.outputs.worker == 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build and push
run: |
echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
docker build -t ghcr.io/${{ github.repository }}/worker:${{ github.sha }} services/worker/
docker push ghcr.io/${{ github.repository }}/worker:${{ github.sha }}
- name: Deploy Worker
run: |
curl -sf -X PATCH \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{"image": "ghcr.io/${{ github.repository }}/worker:${{ github.sha }}"}' \
https://app.sailops.io/api/public/api/v1/containers/worker

GitLab CI​

# .gitlab-ci.yml
stages:
- build
- deploy

.deploy-template: &deploy-template
stage: deploy
image: curlimages/curl:latest
rules:
- if: $CI_COMMIT_BRANCH == "main"

build-api:
stage: build
image: docker:27
services:
- docker:27-dind
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
script:
- docker build -t $CI_REGISTRY_IMAGE/api:$CI_COMMIT_SHA services/api/
- docker push $CI_REGISTRY_IMAGE/api:$CI_COMMIT_SHA
rules:
- if: $CI_COMMIT_BRANCH == "main"
changes:
- services/api/**

deploy-api:
<<: *deploy-template
needs: [build-api]
script:
- |
curl -sf -X PATCH \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"image\": \"$CI_REGISTRY_IMAGE/api:$CI_COMMIT_SHA\"}" \
https://app.sailops.io/api/public/api/v1/containers/api
rules:
- if: $CI_COMMIT_BRANCH == "main"
changes:
- services/api/**

build-worker:
stage: build
image: docker:27
services:
- docker:27-dind
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
script:
- docker build -t $CI_REGISTRY_IMAGE/worker:$CI_COMMIT_SHA services/worker/
- docker push $CI_REGISTRY_IMAGE/worker:$CI_COMMIT_SHA
rules:
- if: $CI_COMMIT_BRANCH == "main"
changes:
- services/worker/**

deploy-worker:
<<: *deploy-template
needs: [build-worker]
script:
- |
curl -sf -X PATCH \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"image\": \"$CI_REGISTRY_IMAGE/worker:$CI_COMMIT_SHA\"}" \
https://app.sailops.io/api/public/api/v1/containers/worker
rules:
- if: $CI_COMMIT_BRANCH == "main"
changes:
- services/worker/**

Approach 2: Stack Engine (Infrastructure as Code)​

Use a YAML stack file to define your entire infrastructure and apply it in CI/CD. Best for managing multiple resources together (containers + databases + gateways + routes + connections).

See the Stack Engine guide for the full stack file format and options.

Stack File Example​

# infra/stack.yaml
containers:
- name: api
spec:
computeClass: standard
image: ghcr.io/myorg/api:${IMAGE_TAG}
resources:
cpu: 500
memory: 512
ports:
- containerPort: 8080
autoscaling:
minReplicas: 2
maxReplicas: 10
cpuThreshold: 70
configuration:
environment:
- key: DATABASE_URL
type: secret
value: "${DATABASE_URL}"
- key: REDIS_URL
type: secret
value: "${REDIS_URL}"

- name: worker
spec:
computeClass: standard
image: ghcr.io/myorg/worker:${IMAGE_TAG}
resources:
cpu: 250
memory: 256

services:
postgresql:
- name: main-db
version: 16
flavor: small
computeClass: standard
storage: 20Gi

valkey:
- name: cache
flavor: small
computeClass: standard

gateways:
- name: main-lb
class: gw-small

routes:
- name: api-route
gateway: main-lb
type: HTTPRoute
httpSpec:
hostnames:
- api.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: api
port: 8080

connections:
- sourceType: container
sourceId: api
targetType: postgresql
targetId: main-db
alias: DB
dedicatedDatabase: true
databaseName: app

- sourceType: container
sourceId: api
targetType: valkey
targetId: cache
alias: CACHE

GitHub Actions — Stack Deployment​

Plan on Pull Request, Apply on Merge​

# .github/workflows/stack-deploy.yml
name: Stack Deploy

on:
pull_request:
paths: ['infra/stack.yaml']
push:
branches: [main]
paths: ['infra/stack.yaml']

jobs:
plan:
runs-on: ubuntu-latest
if: github.event_name == 'pull_request'
steps:
- uses: actions/checkout@v4

- name: Plan stack changes
id: plan
run: |
RESPONSE=$(curl -s -X POST \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat infra/stack.yaml | jq -Rs .),
\"variables\": {
\"IMAGE_TAG\": \"${{ github.sha }}\",
\"DATABASE_URL\": \"${{ secrets.DATABASE_URL }}\",
\"REDIS_URL\": \"${{ secrets.REDIS_URL }}\"
}
}" \
https://app.sailops.io/api/public/api/v1/stack/plan)

echo "$RESPONSE" | jq .
echo "plan_output<<EOF" >> $GITHUB_OUTPUT
echo "$RESPONSE" | jq -r '.changes[] | "- \(.action): \(.resourceType)/\(.name)\(if .details then " (\(.details))" else "" end)"' >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT

- name: Comment PR with plan
uses: actions/github-script@v7
with:
script: |
const plan = `${{ steps.plan.outputs.plan_output }}`;
const body = `## SailOps Stack Plan\n\nChanges that will be applied on merge:\n\n${plan}\n\n_Run by Stack Engine via GitHub Actions_`;
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: body
});

apply:
runs-on: ubuntu-latest
if: github.event_name == 'push'
steps:
- uses: actions/checkout@v4

- name: Apply stack
run: |
RESPONSE=$(curl -s -o /tmp/response.json -w "%{http_code}" -X POST \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat infra/stack.yaml | jq -Rs .),
\"variables\": {
\"IMAGE_TAG\": \"${{ github.sha }}\",
\"DATABASE_URL\": \"${{ secrets.DATABASE_URL }}\",
\"REDIS_URL\": \"${{ secrets.REDIS_URL }}\"
}
}" \
https://app.sailops.io/api/public/api/v1/stack/apply)

if [ "$RESPONSE" -ge 400 ]; then
echo "Stack apply failed:"
cat /tmp/response.json | jq .
exit 1
fi

echo "Stack applied successfully:"
cat /tmp/response.json | jq '.changes[]'

GitLab CI — Stack Deployment​

Plan on MR, Apply on Merge​

# .gitlab-ci.yml
stages:
- plan
- apply

variables:
SAILOPS_API: https://app.sailops.io/api/public/api/v1

stack-plan:
stage: plan
image: curlimages/curl:latest
script:
- apk add --no-cache jq
- |
RESPONSE=$(curl -s -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat infra/stack.yaml | jq -Rs .),
\"variables\": {
\"IMAGE_TAG\": \"$CI_COMMIT_SHA\",
\"DATABASE_URL\": \"$DATABASE_URL\",
\"REDIS_URL\": \"$REDIS_URL\"
}
}" \
$SAILOPS_API/stack/plan)

echo "Stack Plan:"
echo "$RESPONSE" | jq '.changes[] | "\(.action): \(.resourceType)/\(.name)"'
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
changes:
- infra/stack.yaml

stack-apply:
stage: apply
image: curlimages/curl:latest
script:
- apk add --no-cache jq
- |
HTTP_CODE=$(curl -s -o /tmp/response.json -w "%{http_code}" -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat infra/stack.yaml | jq -Rs .),
\"variables\": {
\"IMAGE_TAG\": \"$CI_COMMIT_SHA\",
\"DATABASE_URL\": \"$DATABASE_URL\",
\"REDIS_URL\": \"$REDIS_URL\"
}
}" \
$SAILOPS_API/stack/apply)

if [ "$HTTP_CODE" -ge 400 ]; then
echo "Stack apply failed with HTTP $HTTP_CODE:"
cat /tmp/response.json | jq .
exit 1
fi

echo "Stack applied successfully:"
cat /tmp/response.json | jq '.changes[]'
rules:
- if: $CI_COMMIT_BRANCH == "main"
changes:
- infra/stack.yaml
environment:
name: production

Multi-Environment Deployments​

Use separate stack files or variable overrides to deploy to staging and production.

Project Structure​

infra/
├── stack.yaml # Shared infrastructure definition
├── staging.env # Staging-specific variables (non-secret)
└── production.env # Production-specific variables (non-secret)

GitHub Actions — Staging → Production​

# .github/workflows/multi-env.yml
name: Multi-Environment Deploy

on:
push:
branches:
- main # → staging
- release/** # → production

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Set environment
id: env
run: |
if [[ "${{ github.ref }}" == refs/heads/main ]]; then
echo "env=staging" >> $GITHUB_OUTPUT
echo "api_key_secret=SAILOPS_API_KEY_STAGING" >> $GITHUB_OUTPUT
else
echo "env=production" >> $GITHUB_OUTPUT
echo "api_key_secret=SAILOPS_API_KEY_PRODUCTION" >> $GITHUB_OUTPUT
fi

- name: Build and push image
run: |
echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

- name: Apply stack to ${{ steps.env.outputs.env }}
env:
SAILOPS_API_KEY: ${{ secrets[steps.env.outputs.api_key_secret] }}
run: |
curl -sf -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat infra/stack.yaml | jq -Rs .),
\"variables\": {
\"IMAGE_TAG\": \"${{ github.sha }}\",
\"DATABASE_URL\": \"${{ secrets.DATABASE_URL }}\",
\"REDIS_URL\": \"${{ secrets.REDIS_URL }}\"
}
}" \
https://app.sailops.io/api/public/api/v1/stack/apply

GitLab CI — Staging → Production​

# .gitlab-ci.yml
stages:
- build
- deploy-staging
- deploy-production

build:
stage: build
image: docker:27
services:
- docker:27-dind
before_script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
script:
- docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
rules:
- if: $CI_COMMIT_BRANCH == "main"

deploy-staging:
stage: deploy-staging
image: curlimages/curl:latest
script:
- apk add --no-cache jq
- |
curl -sf -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY_STAGING" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat infra/stack.yaml | jq -Rs .),
\"variables\": {
\"IMAGE_TAG\": \"$CI_COMMIT_SHA\",
\"DATABASE_URL\": \"$DATABASE_URL_STAGING\"
}
}" \
https://app.sailops.io/api/public/api/v1/stack/apply
environment:
name: staging
rules:
- if: $CI_COMMIT_BRANCH == "main"

deploy-production:
stage: deploy-production
image: curlimages/curl:latest
script:
- apk add --no-cache jq
- |
curl -sf -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY_PRODUCTION" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat infra/stack.yaml | jq -Rs .),
\"variables\": {
\"IMAGE_TAG\": \"$CI_COMMIT_SHA\",
\"DATABASE_URL\": \"$DATABASE_URL_PRODUCTION\"
}
}" \
https://app.sailops.io/api/public/api/v1/stack/apply
environment:
name: production
rules:
- if: $CI_COMMIT_BRANCH == "main"
when: manual
allow_failure: false
Separate API Keys per Environment

Each SailOps project has its own API key. Create one project for staging and one for production, each with its own key. This ensures deployments are isolated.


Advanced Patterns​

Export Current State​

Before making changes, export your current infrastructure to a stack file:

curl -H "X-Api-Key: $SAILOPS_API_KEY" \
"https://app.sailops.io/api/public/api/v1/stack/export?format=yaml" \
| jq -r '.stack' > infra/stack.yaml

This is useful for:

  • Bootstrapping IaC from an existing project set up through the UI
  • Auditing drift between your stack file and the live state

Scoped Deployments​

Deploy only containers without touching services or gateways:

curl -sf -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat infra/stack.yaml | jq -Rs .),
\"options\": {\"scope\": [\"containers\"]},
\"variables\": {\"IMAGE_TAG\": \"$IMAGE_TAG\"}
}" \
https://app.sailops.io/api/public/api/v1/stack/apply

Valid scopes: containers, services, gateways, routes, connections.

Run a Database Migration Job​

Trigger a one-time migration job before deploying the new application version:

# GitHub Actions step
- name: Run database migration
run: |
# Create a one-time job
curl -sf -X POST \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{
"name": "migrate-${{ github.run_number }}",
"computeClass": "eco",
"image": "ghcr.io/${{ github.repository }}:${{ github.sha }}",
"resources": {"cpu": 250, "memory": 256},
"command": ["./migrate", "up"],
"backoffLimit": 0
}' \
https://app.sailops.io/api/public/api/v1/jobs

# Wait for completion
for i in $(seq 1 60); do
STATUS=$(curl -sf \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
https://app.sailops.io/api/public/api/v1/jobs/migrate-${{ github.run_number }}/status \
| jq -r '.status')

if [ "$STATUS" = "succeeded" ]; then
echo "Migration completed"
break
elif [ "$STATUS" = "failed" ]; then
echo "Migration failed"
exit 1
fi
sleep 5
done

Update Environment Variables​

Push configuration changes without rebuilding:

curl -sf -X PUT \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"environment": [
{"key": "FEATURE_FLAG_NEW_UI", "type": "config", "value": "true"},
{"key": "API_SECRET", "type": "secret", "value": "'"$API_SECRET"'"}
]
}' \
https://app.sailops.io/api/public/api/v1/containers/my-api/config

Choosing an Approach​

CriteriaDirect API CallsStack Engine
ComplexitySimple — one curl per resourceOne call manages everything
Best forImage updates, config changes, restartsFull infrastructure lifecycle
Drift detectionManualBuilt-in (plan shows diff)
Multi-resourceMultiple calls neededSingle YAML file
RollbackRevert image tag manuallyApply previous stack version
Learning curveLowMedium (learn stack format)
Recommendation

Start with direct API calls for simple deploy-on-push workflows. Adopt the Stack Engine when you manage multiple interconnected resources (containers + databases + gateways) or need drift detection and plan previews.