Deployments, previews and rollbacks

Deploy and redeploy Services, follow a Deployment, request previews, roll back and run schedules.

A Deployment is one attempt to build and release a Service. Every deploy request queues a new Deployment; nothing is merged with a request already waiting. Previews are Deployments of a branch that expire, and a rollback puts an earlier build back.

Every request goes to https://cloudgate.octabyte.app/backend on the Hosted instance, or to your console address followed by /backend when you self-host. Send a Personal key in x-api-key and the Organization in x-organization-id; Authentication shows how to make the key, and Errors explains every refusal. The examples setCLOUDGATE_KEY and CLOUDGATE_ORG_ID in the shell first. To do the same in the console, read Deployments in the user guide.

Deployments

List the Organization's Deployments

GET/deployments

The organization's deployment feed — the read that exists for no single owner, because no route enumerates an Environment's services for a client to fan out over.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
limitqueryinteger1 to 100. Default 20.
cursorquerystringNot empty.
statusquerystringOne of pending, running, done, error, cancelled, held.
projectIdquerystringNot empty.

Responses

200 OK
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.
curl https://cloudgate.octabyte.app/backend/deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List Deployments for an Application

GET/applications/{applicationId}/deployments

An application's deployments.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
applicationIdrequiredpathstringThe Application's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/applications/j9ct9tCzxUD9FjoxV2gtc/deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Deploy an Application

POST/applications/{applicationId}/deployments

Triggers a deployment of an application — deployments are triggered per service.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
applicationIdrequiredpathstringThe Application's id.

Request body

FieldTypeNotes
titlestringNot empty.
descriptionstring

Responses

201 Created
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/applications/j9ct9tCzxUD9FjoxV2gtc/deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "title": "example",
    "description": "Storefront for Northwind Labs"
  }'

Redeploy an Application

POST/applications/{applicationId}/redeploy

Builds again from the source the Application already has. It lives here rather than on the applications controller for the same reason deployments does — it writes a deployment record and enqueues a job, and both of those belong to one service.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
applicationIdrequiredpathstringThe Application's id.

Request body

FieldTypeNotes
titlestringNot empty.
descriptionstring

Responses

201 Created
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/applications/j9ct9tCzxUD9FjoxV2gtc/redeploy \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "title": "example",
    "description": "Storefront for Northwind Labs"
  }'

Cancel a Deployment

POST/deployments/{deploymentId}/cancel

Cancels a deployment.

Who can call it: Owner, Admin or Member. Needs deployment: cancel, which a custom role can also grant.

Parameters

NameInTypeNotes
deploymentIdrequiredpathstringThe Deployment's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/deployments/Wvn8FY3seANNJKRKzcS8C/cancel \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Stop a Cloud run

POST/deployments/{deploymentId}/stop-run

Stop the run: ends a running Cloud run, its apply included.

Who can call it: Owner, Admin or Member. Needs deployment: cancel, which a custom role can also grant.

Parameters

NameInTypeNotes
deploymentIdrequiredpathstringThe Deployment's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/deployments/Wvn8FY3seANNJKRKzcS8C/stop-run \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Build a held push now

POST/deployments/{deploymentId}/build-now

"Build now with saved settings": releases a build a push held for a plan into the queue at once. 200, like cancel: it updates the Deployment named in its path and inserts nothing.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
deploymentIdrequiredpathstringThe Deployment's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/deployments/Wvn8FY3seANNJKRKzcS8C/build-now \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List Deployments for a Compose stack

GET/compose/{composeId}/deployments

A compose stack's deployments.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
composeIdrequiredpathstringThe Compose stack's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/compose/4Eo3MNRPQbdBs6dZEDtLs/deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Deploy a Compose stack

POST/compose/{composeId}/deployments

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
composeIdrequiredpathstringThe Compose stack's id.

Request body

FieldTypeNotes
titlestringNot empty.
descriptionstring

Responses

201 Created
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/compose/4Eo3MNRPQbdBs6dZEDtLs/deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "title": "example",
    "description": "Storefront for Northwind Labs"
  }'

List Deployments for a schedule

GET/schedules/{scheduleId}/deployments

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
scheduleIdrequiredpathstringThe schedule's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/schedules/KZgsRefva9B2gpXrY58oU/deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List Deployments for a volume backup

GET/volume-backups/{volumeBackupId}/deployments

A volume backup's run history.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
volumeBackupIdrequiredpathstringThe volume backup's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/volume-backups/DkBVnhDCBhHPsCHtsXH8k/deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get a Deployment

GET/deployments/{deploymentId}

One Deployment's status and times: pending, running, done, error (failed), cancelled or held, and when it was recorded, started and finished. The Cloudgate CLI asks it while following the Deployment log, whose stream never closes by itself.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
deploymentIdrequiredpathstringThe Deployment's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
Fields of the 200 answer
FieldTypeNotes
deploymentIdalwaysstring
statusalwaysstringOne of pending, running, done, error, cancelled, held.
createdAtalwaysstring
startedAtalwaysstring or null
finishedAtalwaysstring or null
curl https://cloudgate.octabyte.app/backend/deployments/Wvn8FY3seANNJKRKzcS8C \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Read a Deployment log

GET/deployments/{deploymentId}/logs

The tail of a deployment's log file.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
deploymentIdrequiredpathstringThe Deployment's id.
tailqueryinteger1 to 10000. Default 100.

Responses

200 OK
The deployment's log file, most recent tail lines last.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/deployments/Wvn8FY3seANNJKRKzcS8C/logs \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Preview deployments

List preview deployments for an Application

GET/applications/{applicationId}/preview-deployments

An application's preview deployments.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
applicationIdrequiredpathstringThe Application's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/applications/j9ct9tCzxUD9FjoxV2gtc/preview-deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Request a preview

POST/applications/{applicationId}/preview-deployments

Asks for a Requested preview of a branch. 201 with the preview, its printed link and the queued Deployment's id.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
applicationIdrequiredpathstringThe Application's id.

Request body

FieldTypeNotes
branchrequiredstring1 to 255 characters. Matches ^(?!-)(?!.*\.\.)[^\s\x00-\x1f\x7f~^:?*[\\]+$.
ttlMinutesintegerAt least 1.

Responses

201 Created
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/applications/j9ct9tCzxUD9FjoxV2gtc/preview-deployments \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "branch": "main"
  }'

Extend a preview deployment

POST/preview-deployments/{previewDeploymentId}/extend

Moves a Requested preview's expiry to now plus the TTL.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
previewDeploymentIdrequiredpathstringThe preview deployment's id.

Request body

FieldTypeNotes
ttlMinutesintegerAt least 1.

Responses

200 OK
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/preview-deployments/CCUrFwSypmsMVXBphPohH/extend \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "ttlMinutes": 1
  }'

Get a preview deployment

GET/preview-deployments/{previewDeploymentId}

One preview deployment.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
previewDeploymentIdrequiredpathstringThe preview deployment's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/preview-deployments/CCUrFwSypmsMVXBphPohH \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Delete a preview deployment

DELETE/preview-deployments/{previewDeploymentId}

Tears a pull-request preview down without waiting for its PR to close, or expires a Requested preview now and answers at once: the expiry sweep tears it down within the minute.

Who can call it: Owner, Admin or Member. Needs deployment: cancel, which a custom role can also grant.

Parameters

NameInTypeNotes
previewDeploymentIdrequiredpathstringThe preview deployment's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X DELETE https://cloudgate.octabyte.app/backend/preview-deployments/CCUrFwSypmsMVXBphPohH \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Redeploy a preview deployment

POST/preview-deployments/{previewDeploymentId}/redeploy

Re-enqueues the preview's build, and answers the queued Deployment.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
previewDeploymentIdrequiredpathstringThe preview deployment's id.

Request body

FieldTypeNotes
titlestring
descriptionstring

Responses

201 Created
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/preview-deployments/CCUrFwSypmsMVXBphPohH/redeploy \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "title": "example",
    "description": "Storefront for Northwind Labs"
  }'

Rollbacks

List rollback snapshots for an Application

GET/applications/{applicationId}/rollbacks

Rollback snapshots are listed per application, like deployments.

Who can call it: Owner, Admin or Member. Needs deployment: read, which a custom role can also grant.

Parameters

NameInTypeNotes
applicationIdrequiredpathstringThe Application's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/applications/j9ct9tCzxUD9FjoxV2gtc/rollbacks \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Roll back to a snapshot

POST/rollbacks/{rollbackId}/rollback

Rolls the application back onto this snapshot. The service answers which (deploymentId).

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
rollbackIdrequiredpathstringThe rollback's id.

Responses

202 Accepted
The Rollback is under way. deploymentId is the queued Deployment of a static site on AWS, whose log shows it; null on a Server, where Swarm converges the service onto the snapshot's image.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
Fields of the 202 answer
FieldTypeNotes
deploymentIdalwaysstring or null
curl -X POST https://cloudgate.octabyte.app/backend/rollbacks/vftW7UyFnqJd4HiCMS7Xv/rollback \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Delete a rollback snapshot

DELETE/rollbacks/{rollbackId}

Deletes a snapshot: its preserved image, then its row.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

NameInTypeNotes
rollbackIdrequiredpathstringThe rollback's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X DELETE https://cloudgate.octabyte.app/backend/rollbacks/vftW7UyFnqJd4HiCMS7Xv \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Schedules

List schedules

GET/schedules

Who can call it: Owner, Admin or Member. Needs schedule: read, which a custom role can also grant.

Parameters

NameInTypeNotes
scheduleTyperequiredquerystringOne of application, compose, server, cloudgate-server.
serviceIdquerystring

Responses

200 OK
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.
curl "https://cloudgate.octabyte.app/backend/schedules?scheduleType=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create a schedule

POST/schedules

Who can call it: Owner, Admin or Member. Needs schedule: create, which a custom role can also grant.

Request body

FieldTypeNotes
namerequiredstringNot empty.
descriptionstring
cronExpressionrequiredstringNot empty.
scheduleTypestringOne of application, compose, server, cloudgate-server. Default "application".
serviceIdstring
serviceNamestring
shellTypestringOne of bash, sh. Default "bash".
commandstring
scriptstring
enabledboolean
timezonestring

Responses

201 Created
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/schedules \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "storefront",
    "cronExpression": "0 3 * * *"
  }'

Get a schedule

GET/schedules/{id}

Who can call it: Owner, Admin or Member. Needs schedule: read, which a custom role can also grant.

Parameters

NameInTypeNotes
idrequiredpathstringThe schedule's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl https://cloudgate.octabyte.app/backend/schedules/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a schedule

PATCH/schedules/{id}

Who can call it: Owner, Admin or Member. Needs schedule: update, which a custom role can also grant.

Parameters

NameInTypeNotes
idrequiredpathstringThe schedule's id.

Request body

FieldTypeNotes
namestringNot empty.
descriptionstring or null
cronExpressionstringNot empty.
serviceNamestring or null
shellTypestringOne of bash, sh.
commandstring
scriptstring or null
enabledboolean
timezonestring or null

Responses

200 OK
The result, as JSON.
Refusals
400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X PATCH https://cloudgate.octabyte.app/backend/schedules/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "storefront",
    "description": "Storefront for Northwind Labs",
    "cronExpression": "0 3 * * *"
  }'

Delete a schedule

DELETE/schedules/{id}

Who can call it: Owner, Admin or Member. Needs schedule: delete, which a custom role can also grant.

Parameters

NameInTypeNotes
idrequiredpathstringThe schedule's id.

Responses

200 OK
The result, as JSON.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X DELETE https://cloudgate.octabyte.app/backend/schedules/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Run a schedule now

POST/schedules/{id}/run

Who can call it: Owner, Admin or Member. Needs schedule: create, which a custom role can also grant.

Parameters

NameInTypeNotes
idrequiredpathstringThe schedule's id.

Responses

204 No content
Done. The answer has no body.
Refusals
401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.
curl -X POST https://cloudgate.octabyte.app/backend/schedules/RAU6yAYUXFRdXdPLyLoPC/run \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Something missing or wrong on this page? Email support@octabyte.io, or start a free trial and try it in the console.