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:
| Approach | Best For | How It Works |
|---|---|---|
| Direct API calls | Simple deployments (update image, restart) | Call specific endpoints like PATCH /containers/{name} |
| Stack Engine | Full infrastructure management | Define 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)
- GitHub Actions:
Approach 1: Direct API Calls
Use individual API endpoints to update specific resources. Best for simple workflows like "build image, update container."
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
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
| Criteria | Direct API Calls | Stack Engine |
|---|---|---|
| Complexity | Simple — one curl per resource | One call manages everything |
| Best for | Image updates, config changes, restarts | Full infrastructure lifecycle |
| Drift detection | Manual | Built-in (plan shows diff) |
| Multi-resource | Multiple calls needed | Single YAML file |
| Rollback | Revert image tag manually | Apply previous stack version |
| Learning curve | Low | Medium (learn stack format) |
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.
Related Topics
- Public API Overview — Authentication, base URL, error format
- Stack Engine — Full stack file format and options
- API Endpoints — Complete endpoint reference
- API Keys — Create and manage API keys