Automating Deployments

Track deployments to understand how changes impact performance. Deploys allow you to see timeline markers for code deployments.

Create deploy

Required API Permission: Create Deploys

To create deploys as part of your continuous integration or deployment system, add revision, repository and username details:

You can create deploys with the CLI, Node.js API, HTTP Site API or GraphQL API.

1calibre site create-deploy --site=<site> --revision=<revision> \
2--repository=<repository> --username=<username>

1import { Deploy } from 'calibre'
2
3await Deploy.create({
4  site: '<site>',
5  revision: '<revision>',
6  repository: '<repository>',
7  username: '<username>',
8  createdAt: '<createdAt>'
9})

1curl -X POST -H "Accept: application/json" \
2https://calibreapp.com/api/sites/<site>/deploys?secret=<secret> \
3&revision=<revision>&repository=<repository>&username=<username> \
4&created_at=<createdAt>

Example Response

1✔ Deploy created: cddd1ae9-4af3-4f0e-b9d5-8e26b7848ae3

1{
2  "uuid": "cd080161-a268-4084-9837-0fd9c4a5d545",
3  "revision": "v100",
4  "repository": "https://github.com/calibreapp",
5  "createdAt": "2019-04-24T18:11:00Z"
6}

1{
2  "uuid": "e68302fb-b6e4-4b9c-ae7f-47c8ea6450a3",
3  "organisation_id": "calibre",
4  "site_id": "calibre",
5  "revision": "be549298d1688f166225426f4ea53d15c7c8e815",
6  "repository": "https://github.com/calibreapp/app",
7  "username": "Deployer",
8  "html_url": "https://calibreapp.com/calibre/calibre/deploys/e68302fb-b6e4-4b9c-ae7f-47c8ea6450a3",
9  "url": "https://calibreapp.com/api/sites/calibre/deploys/e68302fb-b6e4-4b9c-ae7f-47c8ea6450a3.json",
10  "created_at": "2023-07-17T23:02:39.212Z"
11}

Parameter	Required	Description
site	Yes	Site slug, found in site settings
revision	No	Source control revision id of the code being deployed (e.g. git hash or tag name)
repository	No	Base URL of the repository containing the source code being deployed (e.g. https://github.com/calibreapp/app)
username	No	Name of the user who deployed the code
createdAt	No	The ISO8601 timestamp when the deploy was created

List deploys

Required API Permission: Read Sites

You can list deploys with the CLI, Node.js API, HTTP Site API or GraphQL API.

1calibre site deploys --site=<site> --count=<count> --cursor=<cursor>

1import { Deploy } from 'calibre'
2
3await Deploy.list({
4  site: '<site>',
5  count: <count>,
6  cursor: '<cursor>'
7})

1curl -X GET -H "Accept: application/json" \
2https://calibreapp.com/api/sites/<site>/deploys?secret=<secret>

Example Response

15 deploys
2UUID                                 | REVISION | REPOSITORY                        | USERNAME | CREATED
36725fd7d-1102-430f-a9fe-654bae14e1b3 | v30      | https://github.com/calibreapp/app | Deployer | 10:00pm 12-Jul-2019
4e6027c27-ebc5-4172-8412-5fe37e23a12e | v29      | https://github.com/calibreapp/app | Deployer | 8:00pm 11-Jul-2019
5ffd67e01-8e76-424d-9688-160b63396aec  | v28      | https://github.com/calibreapp/app | Deployer | 12:00pm 10-Jul-2019
642324d05-3e7d-4dd9-be7b-370af03ec1eb | v27      | https://github.com/calibreapp/app | Deployer | 6:00pm 9-Jul-2019
7badd5ad0-932a-424b-a075-d3319650856d | v26      | https://github.com/calibreapp/app | Deployer | 1:00am 9-Jul-2019
8To see deploys after v26, run: calibre site deploys --site=calibre --cursor=Nw

1{
2  "deploys": [
3    {
4      "uuid": "6725fd7d-1102-430f-a9fe-654bae14e1b3",
5      "revision": "v30",
6      "repository": "https://github.com/calibreapp/app",
7      "username": "Deployer",
8      "createdAt": "2019-07-12T12:00:00Z"
9    },
10  ],
11  "pageInfo": {
12    "hasPreviousPage": false,
13    "hasNextPage": true,
14    "endCursor": "Nw",
15    "startCursor": "MQ"
16  }
17}

1[
2  {
3    "uuid": "badd5ad0-932a-424b-a075-d3319650856d",
4    "organisation_id": "calibre",
5    "site_id": "calibre",
6    "revision": "v26",
7    "repository": "https://github.com/calibreapp/app",
8    "username": "Deployer",
9    "html_url": "https://calibreapp.com/calibre/calibre/deploys/e68302fb-b6e4-4b9c-ae7f-47c8ea6450a3",
10    "url": "https://calibreapp.com/api/sites/calibre/deploys/e68302fb-b6e4-4b9c-ae7f-47c8ea6450a3.json",
11    "created_at": "2019-07-17T23:02:39.212Z"
12  }
13]

Parameter	Required	Description
site	Yes	Site slug, found in site settings
count	No	The number of records to return, maximum: 500
cursor	No	The cursor to fetch records after

Delete deploy

Required API Permission: Delete Deploys

You can delete a deploy with the CLI, Node.js API or GraphQL API.

1calibre site delete-deploy --site=<site> --uuid-<uuid> --confirm

1import { Deploy } from 'calibre'
2
3await Deploy.destroy({
4  site: '<site>',
5  uuid: '<uuid>'
6})

Example Response

1✔ Deploy deleted: e68302fb-b6e4-4b9c-ae7f-47c8ea6450a3

1{
2  "uuid": "cddd1ae9-4af3-4f0e-b9d5-8e26b7848ae3"
3}

Parameter	Required	Description
site	Yes	Site slug, found in site settings
uuid	Yes	The uuid of the deploy

Retrieve deploy

You can retrieve a deploy with the HTTP Site API.

1curl -X GET -H "Accept: application/json" \
2https://calibreapp.com/api/sites/<site>/deploys/<uuid>?secret=<secret>

Example Response

1{
2  "uuid": "badd5ad0-932a-424b-a075-d3319650856d",
3  "organisation_id": "calibre",
4  "site_id": "calibre",
5  "revision": "v26",
6  "repository": "https://github.com/calibreapp/app",
7  "username": "Deployer",
8  "html_url": "https://calibreapp.com/calibre/calibre/deploys/e68302fb-b6e4-4b9c-ae7f-47c8ea6450a3",
9  "url": "https://calibreapp.com/api/sites/calibre/deploys/e68302fb-b6e4-4b9c-ae7f-47c8ea6450a3.json",
10  "created_at": "2019-07-17T23:02:39.212Z"
11}

Parameter	Required	Description
site	Yes	Site slug, found in site settings
uuid	Yes	The uuid of the deploy

Heroku deployment tracking

You can track deploys using Heroku release phases.

Tip

The following example expects that Node.js is installed on your Heroku dyno.

You can add a release phase by updating Procfile to include a release command:

1web: node index.js
2release: scripts/heroku-release.sh

Then, in scripts/heroku-release.sh, add the following:

1#!/usr/bin/env bash
2
3set -o errexit
4set -o nounset
5set -o pipefail
6
7echo "Marking the deployment in Calibre"
8npx --yes calibre site create-deploy --site=calibre --revision="$HEROKU_SLUG_COMMIT" --repository="https://github.com/calibreapp/app"
9
10echo "Creating a snapshot in Calibre"
11npx --yes calibre site create-snapshot --site=calibre --ref="$HEROKU_SLUG_COMMIT"

Finally, update your Heroku application pipeline to include a CALIBRE_API_TOKEN environment variable. You can learn how to generate a token on the API Tokens page.