Deployments

Deployments track the history of changes to your services. Every time you update a service, a deployment record is created, allowing you to view history and roll back to previous versions.

Endpoints

Method	Endpoint	Description
GET	/api/deployments/	List all your deployments
GET	/api/deployments/{id}/	Get deployment details
GET	/api/services/{id}/deployments/	List deployments for a service
POST	/api/deployments/{id}/rollback/	Roll back to a deployment

Deployment Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "service": "service-uuid",
  "version_number": 5,
  "image": "myapp:v1.2.0",
  "port": 8080,
  "replicas": 3,
  "config_snapshot": {
    "API_URL": "https://api.example.com",
    "LOG_LEVEL": "info"
  },
  "secret_keys_snapshot": ["DATABASE_PASSWORD", "API_KEY"],
  "status": "success",
  "deployed_at": "2024-10-15T12:00:00Z",
  "deployed_by": "user-uuid",
  "rollback_from": null,
  "notes": "",
  "error_message": ""
}

Fields

Field	Type	Description
id	UUID	Unique identifier
service	UUID	Service this deployment belongs to
version_number	integer	Sequential version number
image	string	Docker image deployed
port	integer	Port configuration
replicas	integer	Number of replicas
config_snapshot	object	Copy of config values at deployment time
secret_keys_snapshot	array	List of secret keys (values not included)
status	string	Deployment status
deployed_at	datetime	When deployment occurred
deployed_by	UUID	User who triggered the deployment
rollback_from	UUID	Original deployment if this is a rollback
notes	string	Optional deployment notes
error_message	string	Error details if deployment failed

Status Values

Status	Meaning
pending	Deployment in progress
success	Deployment completed successfully
failed	Deployment failed
rolled_back	This version was rolled back from

List Deployments

All Deployments

GET /api/deployments/

Deployments for a Service

GET /api/services/{service_id}/deployments/

Example:

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/services/abc123.../deployments/

Response:

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "deploy5...",
      "version_number": 5,
      "status": "success",
      "image": "myapp:v1.2.0",
      "deployed_at": "2024-10-15T12:00:00Z"
    },
    {
      "id": "deploy4...",
      "version_number": 4,
      "status": "failed",
      "image": "myapp:v1.1.0",
      "deployed_at": "2024-10-14T10:00:00Z"
    },
    {
      "id": "deploy3...",
      "version_number": 3,
      "status": "success",
      "image": "myapp:v1.0.2",
      "deployed_at": "2024-10-13T08:00:00Z"
    }
  ]
}

Deployments are returned in reverse chronological order (newest first).

Get Deployment Details

GET /api/deployments/{id}/

Example:

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/deployments/deploy5.../

Response:

{
  "id": "deploy5...",
  "service": "abc123...",
  "version_number": 5,
  "image": "myapp:v1.2.0",
  "port": 8080,
  "replicas": 3,
  "config_snapshot": {
    "API_URL": "https://api.example.com",
    "LOG_LEVEL": "info"
  },
  "secret_keys_snapshot": ["DATABASE_PASSWORD", "API_KEY"],
  "status": "success",
  "deployed_at": "2024-10-15T12:00:00Z",
  "deployed_by": "user-uuid",
  "rollback_from": null,
  "notes": "",
  "error_message": ""
}

Security

Secret values are not included in the snapshot - only the key names. This protects sensitive data in deployment history.

Roll Back

Roll back a service to a previous successful deployment:

POST /api/deployments/{id}/rollback/

Request Body (Optional):

{
  "notes": "Rolling back due to bug in v1.2.0"
}

Example:

curl -X POST https://api.example.com/api/deployments/deploy3.../rollback/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Rolling back to stable version"}'

Response (201 Created):

Returns the new deployment created by the rollback:

{
  "id": "deploy6...",
  "version_number": 6,
  "image": "myapp:v1.0.2",
  "status": "pending",
  "rollback_from": "deploy3...",
  "notes": "Rolling back to stable version"
}

Rollback Rules

• You can only roll back to deployments with status: "success"
• Rollback creates a new deployment (doesn't modify existing records)
• The new deployment links to the original via rollback_from
• Version numbers always increment (rollback to v3 creates v6, not v3 again)

Failed Rollback Attempt

{
  "error": "Cannot rollback to deployment with status 'failed'"
}

Automatic Deployment Creation

Deployments are created automatically when you:

1. Create a service - Initial deployment (v1)
2. Update the image - New deployment
3. Change the port - New deployment
4. Scale replicas - New deployment

# This creates a new deployment
curl -X PATCH https://api.example.com/api/services/abc123.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"image": "myapp:v1.3.0"}'

Deployment History Retention

Goblins keeps the last 10 deployments per service:

• Older deployments are automatically deleted
• Current deployment is always retained
• This prevents unbounded storage growth

Example Workflows

View Deployment History

# Get all deployments for a service
curl -H "Authorization: Bearer $API_KEY" \
  https://api.example.com/api/services/$SERVICE_ID/deployments/

Roll Back After Failed Deployment

# 1. List deployments to find last successful
DEPLOYMENTS=$(curl -s -H "Authorization: Bearer $API_KEY" \
  https://api.example.com/api/services/$SERVICE_ID/deployments/)

# 2. Find last successful deployment
LAST_GOOD=$(echo $DEPLOYMENTS | jq -r '.results[] | select(.status=="success") | .id' | head -1)

# 3. Roll back
curl -X POST https://api.example.com/api/deployments/$LAST_GOOD/rollback/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Automatic rollback after failed deployment"}'

Monitor Deployment Status

# After updating a service, poll for deployment status
while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $API_KEY" \
    https://api.example.com/api/services/$SERVICE_ID/ | jq -r '.status')

  if [ "$STATUS" = "ready" ]; then
    echo "Deployment successful!"
    break
  elif [ "$STATUS" = "error" ]; then
    echo "Deployment failed!"
    exit 1
  fi

  echo "Status: $STATUS - waiting..."
  sleep 5
done

Deployment Strategies

Blue-Green Deployment

1. Deploy new version as a separate service
2. Test the new service
3. Update route to point to new service
4. Delete old service

# Create new service with new version
curl -X POST https://api.example.com/api/services/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app-v2",
    "image": "myapp:v2.0.0",
    "port": 8080,
    "config": "'$CONFIG_ID'",
    "secret": "'$SECRET_ID'"
  }'

# After testing, update route
curl -X PATCH https://api.example.com/api/routes/$ROUTE_ID/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "new-service-id"}'

Rolling Update (Default)

Simply update the image - Goblins handles the rolling update:

curl -X PATCH https://api.example.com/api/services/$SERVICE_ID/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "myapp:v2.0.0"}'

Next Steps

• Services - Manage services that create deployments
• Routes - Configure traffic routing