Automating Deployments | Calibre Documentation

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

Create deploy#

Create Deploys

To create a deploy you will need your site-slug and either your site-secret or an API Token with permissions to create deploys.

Your site-slug and site-secret can be found on the Site → Settings → General page, or retrieved via API.

Site settings showing the Site slug and Site secret fields

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

calibre site create-deploy \
	--site=$SITE_SLUG \
	--revision=$REVISION \
	--repository=$REPOSITORY \
	--username=$USERNAME

import { Deploy } from 'calibre'

await Deploy.create({
  site: '<site>',
  revision: '<revision>',
  repository: '<repository>',
  username: '<username>',
  createdAt: '<createdAt>'
})

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

Example Response#

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

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

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

Parameter	Required	Description
site	Yes	The site slug
revision	Yes	The revision identifier (e.g. commit SHA or version number)
repository	No	The repository URL
username	No	The username of the person who triggered the deploy
createdAt	No	The timestamp of the deploy (ISO 8601 format)

List deploys#

Read Sites

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

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

import { Deploy } from 'calibre'

await Deploy.list({
  site: '<site>',
  count: <count>,
  cursor: '<cursor>'
})

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

Delete deploy#

Delete Deploys

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

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

import { Deploy } from 'calibre'

await Deploy.destroy({
  site: '<site>',
  uuid: '<uuid>'
})

Retrieve deploy#

You can retrieve a deploy with the HTTP Site API.

HTTP Site API

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

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:

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

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

#!/usr/bin/env bash

set -o errexit
set -o nounset
set -o pipefail

echo "Marking the deployment in Calibre"
npx --yes calibre site create-deploy \
	--site=calibre \
	--revision="$HEROKU_SLUG_COMMIT" \
	--repository="https://github.com/calibreapp/app"

echo "Creating a snapshot in Calibre"
npx --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.