Deployments

The deployments information are available in read-only. They are populated when application are deployed.

Deployment attributes

field	type	description
id	string	unique ID
app_id	string	unique ID referencing the app this deployment belongs to
created_at	date	date of creation
status	string	status of the deployment (building, success, aborted, *-error)
git_ref	string	git SHA
pusher	object	embedded user who pushed the GIT reference
links	object	hypermedia links about the deployment
image_size	integer	size of the deployment image (in bytes)
stack_base_image	string	stack used as base image

Deployment pusher attributes

field	type	description
id	string	unique ID
email	string	email of user who pushed
username	string	username on Scalingo’s platform

Deployment links attributes

field	type	description
output	string	URL to the logs of the deployment

Example object:

{
  "app_id": "54100930736f7563d5030000",
  "created_at": "2014-09-10T10:49:42.390+02:00",
  "status": "success",
  "git_ref": "abcdef1234567890",
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "image_size": 104857600,
  "stack_base_image": "scalingo/ubuntu-20:v4",
  "pusher": {
    "email": "user@example.com",
    "id": "54100245736f7563d5000000",
    "username": "john"
  },
  "links": {
    "output": "https://$SCALINGO_API_URL/v1/deployments/123e4567-e89b-12d3-a456-426655440000/output"
  }
}

List the deployments of an app

GET https://$SCALINGO_API_URL/v1/apps/[:app]/deployments

This endpoint returns data of several deployments

This endpoint supports pagination.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/apps/example-app/deployments

Returns 200 OK

{
    "deployments": [
        {
            "app_id": "54100930736f7563d5030000",
            "created_at": "2014-09-10T10:49:42.390+02:00",
            "git_ref": "abcdef1234567890",
            "status": "build-error",
            "id": "123e4567-e89b-12d3-a456-426655440000",
            "image_size": 104857600,
            "stack_base_image": "scalingo/ubuntu-20:v4",
            "pusher": {
                "email": "user@example.com",
                "id": "54100245736f7563d5000000",
                "username": "john"
            }
        }
    ],
    "meta": {
        "pagination": {
            "current_page": 1,
            "prev_page": null,
            "next_page": null,
            "total_pages": 1,
            "total_count": 1
        }
    }
}

Get a particular deployment

GET https://$SCALINGO_API_URL/v1/apps/[:app]/deployments/[:deployment_id]

This endpoint returns data of a given deployment from its ID

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/apps/example-app/deployments/123e4567-e89b-12d3-a456-426655440000

Returns 200 OK

{
    "deployment": {
        "app_id": "54100930736f7563d5030000",
        "created_at": "2014-09-10T10:49:42.390+02:00",
        "git_ref": "abcdef1234567890",
        "id": "123e4567-e89b-12d3-a456-426655440000",
        "image_size": 104857600,
        "stack_base_image": "scalingo/ubuntu-20:v4",
        "pusher": {
            "email": "user@example.com",
            "id": "54100245736f7563d5000000",
            "username": "john"
        }
   }
}

Trigger manually a deployment from a GitHub repository

POST https://$SCALINGO_API_URL/v1/apps/[:app]/deployments

With this helper, you’ll be able to trigger a deployment from your application without doing it by a git push.

Attributes

{
  "deployment": {
    "git_ref": "SHA git to deploy",
    "source_url": "Archive with the source"
  }
}

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
     -H "Authorization: Bearer $BEARER_TOKEN" \
     -X POST https://$SCALINGO_API_URL/v1/apps/example-app/deployments -d \
     '{
       "deployment": {
         "git_ref": "master",
         "source_url": "https://github.com/Scalingo/sample-go-martini/archive/master.tar.gz"
       }
     }'

Returns 200 OK

{
  "deployment": {
    "id":"5e34a76a-24b7-4d50-be96-942ca986a786",
    "created_at":"2016-12-16T16:33:58.250+01:00",
    "app_id":"529ba36e65d972e883203922",
    "finished_at":null,
    "status":"building",
    "git_ref":"master",
    "previous_git_ref":"eb5454c314e2e9c8f98efa9b4422476b391df185",
    "duration":0,
    "image_size": 104857600,
    "stack_base_image": "scalingo/ubuntu-20:v4",
    "pusher": {
      "username":"user",
      "email":"user@example.com",
      "id":"51161e5ef1e42617000001"
    },
    "links": {
      "output": "https://$SCALINGO_API_URL/v1/apps/529ba36e65d972e883203922/deployments/5e34a76a-24b7-4d50-be96-942ca986a786/output"
    }
  }
}

Trigger manually a deployment from an archive

POST https://$SCALINGO_API_URL/v1/apps/[:app]/deployments

With this helper, you’ll be able to trigger a deployment from your application without doing it by a git push. You just need to provide a link to an archive containing the sources. The archive must follow some format:

tar archive compressed with gzip
the tar archive MUST contain a single folder at the root. This folder contains the sources of your application.

The git_ref is optional. You can use this attribute to provide any string identifying your archive.

The Sources endpoints have been creating in order to let you upload the code temporarily at some place and get a source_url for your code.

Attributes

{
  "deployment": {
    "git_ref": "Reference in git to deploy",
    "source_url": "Archive with the source"
  }
}

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
     -H "Authorization: Bearer $BEARER_TOKEN" \
     -X POST https://$SCALINGO_API_URL/v1/apps/example-app/deployments -d \
     '{
       "deployment": {
         "git_ref": "v0.0.2",
         "source_url": "https://github.com/Scalingo/sample-go-martini/archive/master.tar.gz"
       }
     }'

Returns 200 OK

{
  "deployment": {
    "id":"5e34a76a-24b7-4d50-be96-942ca986a786",
    "created_at":"2016-12-16T16:33:58.250+01:00",
    "app_id":"529ba36e65d972e883203922",
    "finished_at":null,
    "status":"building",
    "git_ref":"v0.0.2",
    "previous_git_ref":"v0.0.1",
    "type": "archive",
    "duration":0,
    "image_size": 104857600,
    "stack_base_image": "scalingo/ubuntu-20-4",
    "pusher": {
      "username":"user",
      "email":"user@example.com",
      "id":"51161e5ef1e42617000001"
    },
    "links": {
      "output": "https://$SCALINGO_API_URL/v1/apps/529ba36e65d972e883203922/deployments/5e34a76a-24b7-4d50-be96-942ca986a786/output"
    }
  }
}

Get the output of the deployment

GET https://$SCALINGO_API_URL/v1/apps/[:app]/deployments/[:deployment_id]/output

This endpoint will return all the log of the deployment. Those are basically what you have seen in your terminal when running git push.

Example request

curl -H "Accept: text/plain" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/apps/example-app/deployments/123e4567-e89b-12d3-a456-426655440000/output

Returns 200 OK Content-Type: text/plain

-----> Buildpack version 1.2.0
-----> Compiling Ruby/Rails
-----> Using Ruby version: ruby-2.2.2
-----> Installing dependencies using 1.6.3
       Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment
       Using json 1.8.2
       Using rake 10.4.2
       Using thread_safe 0.3.5
       Using builder 3.2.2
       [...]
       Using compass-rails 2.0.4
       Using ember-rails 0.18.2
       Your bundle is complete!
       Gems in the groups development and test were not installed.
       It was installed into ./vendor/bundle
       Bundle completed (2.64s)
       Cleaning up the bundler cache.
-----> Preparing app for Rails asset pipeline
       Running: rake assets:precompile
       I, [2015-05-12T21:45:45.836623 #191]  INFO -- : Writing /build/b7dd3507ecdd8019252dd870615d9d92/public/assets/application-60470b7668df29a6c53fbd61784165a6.js
       Asset precompilation completed (24.44s)
       Cleaning assets
       Running: rake assets:clean

----- Procfile declares types -> web

Get real time output of a live deployment

Real time output comes from a WebSocket

You have to get the URL from the .links.deployments_stream value of an app object, it usually looks like to wss://deployments.scalingo.com/apps/[:app] but may change in the future. That’s why you have to first get an app and read the URL from there.

First thing to do when connected is to authenticate sending an auth frame:

{
  "type": "auth",
  "data": {
     "token": <api token>
  }
}

On authentication error, the websocket will be ended immediately.

Otherwise you’ll start receiving existing logs and real time logs for the app deployments. There can’t be several deployments in parallel for a given application.

Event types

You’ll receive different types of message from the websocket:

ping which is sent to keep the connection open and avoid timeout.
new when a new deployment is triggered this event is sent to notify listeners
log each time a log line is displayed, it is sent through this kind of event
status the deployment goes through multiple states during its lifetime:

  queued -> building → pushing → starting → success
                     → pushing → starting → crashed-error
                     → pushing → starting → timeout-error
                     → pushing → aborted
                     → aborted
                     → build-error

Details about the deployment statuses

queued: deployment is waiting for a slot on our schedulers
building: when the buildpack is chosen and executed
pushing: the generated Docker image is pushed to our registry
starting: the order to start your app has been transmitted to our scheduler
success: the application has correctly started, end of deployment
crashed-error: the application failed to boot, have a look to the logs
timeout-error: the application has not started in 60 seconds
build-error: something went wrong during the buildpack execution, have a look at deployments logs
aborted: if the connection is broken between the pusher and our infrastructure, the deployment is considered as canceled.

Events example

New Event

{
  "type": "new",
  "data": {
    "deployment": "123e4567-e89b-12d3-a456-426655440000"
  }
}

Output Event

{
  "type": "log",
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "data": {
    "content": "Bundle completed (2.64s)"
  }
}

Status Event

{
  "type": "status",
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "data": {
    "status": "success"
  }
}

Ping Event

{
  "type": "ping",
  "data": {
    "ts": 1465288802
  }
}

Manually reset the deployment cache

DELETE https://$SCALINGO_API_URL/v1/apps/[:app]/caches/deployment

To speed up deployment, some files (like dependencies, intermediate builds, etc.) are stored in a cache that we call the deployment cache. This will accelerate deployments since if a dependency is in the deployment cache, we wont need to download it again.

However sometime this deployment cache get corrupted by a deployment or contains some outdated libs that prevent users to update their dependencies.

With this helper you’ll be able to manually clean up the deployment cache.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X DELETE 'https://$SCALINGO_API_URL/v1/apps/my-app/caches/deployment'

Returns 204 No Content