Sending deployments via API to measure Change Failure Rate and Mean Time To Recovery

Swarmia can ingest deployment information directly from your CI/CD pipeline via GitHub checks, or from other systems via an API. In this article we focus on sending deployments via the API.

You can measure Change Failure Rate and Mean Time To Recovery from DORA
metrics by informing Swarmia about deployments of your app, and fixes to the previous
deployments.

 

To send the deployment information, you can use Swarmia's deployments API.
There's two types of requests you can send:

1. Deployment: Sent each time you’ve successfully deployed a change to your
   app. Note that whether or not this deployment later becomes a Change Failure is
   not yet known - if you knew it will cause issues when deployed, you would not
   deploy it!
2. Fix deployment: Sent each time you’re attempting to fix an issue with a
   previously deployed version of your app.

Both are sent via the same API, but with slightly different data.

Authorization

You need to send Authorization header with access token to successfully make the API requests. If you do not have your authorization information please contact us through hello@swarmia.com.

Sending a deployment

To tell Swarmia about a deployment, make an HTTP POST request
to https://hook.swarmia.com/deployments. This can be done from a CI run, deployment
script, or even manually depending on your process. The request body is JSON and
supports these fields:

• version (required) Identifier for the version that just got deployed. Depending
  on the conventions of your organization, app or team, this might be a semverstring
  (e.g. v2.0.5 ), a release tag (e.g. 20220 413-add-widget-support ), or a simple
  git commit hash (e.g. 56e8130 ). The same version can be deployed multiple
  times: for example, when rolling out v2.0.5 of your app, you might first deploy it
  to a staging environment, and only later to production.
• appName Identifier for the app or system. Used to specify which internal
  system of your organization the deployment was related to. If you have a
  separate repository for each app, you can just use the repo name here. If you
  have a monorepo setup, you may want to specify something more precise, e.g.
  frontend or backend . If not provided, will be set to the value default.
• environment Identifier for the app's environment. For example production or staging. If not provided, will be set to the value default.
• deployedAt Timestamp in ISO 8601 format. For example 2022-04-
  11T02:22:47Z . Defaults to current time.
• description Optional string description for the deployment. Maximum length 2048 characters.

Example request with curl

curl -X POST \
  https://hook.swarmia.com/deployments \
  -H "Authorization: $AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v2.0.5",
    "appName": "frontend",
    "environment": "production",
    "deployedAt": "2022-04-11T02:22:47Z"
  }'

Sending a fix deployment

The request is exactly the same as for a regular deployment, but with one extra
required field:

• fixesVersion (required) Version of a previous deployment, which introduced an
  issue that was fixed by this new deployment.

Example request with curl

curl -X POST \
  https://hook.swarmia.com/deployments \
  -H "Authorization: $AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v2.0.6",
    "fixesVersion": "v2.0.5",
    "appName": "frontend",
    "environment": "production"
  }'

Updating existing deployments

Updates can be used to for example mark an existing deployment as a fix to another deployment, or to update the description.

When receiving deployments, we default to creating new deployments. It's a valid use case to deploy the same version twice. However, when the following parameters are defined and they match an existing deployment, we treat the request as an update:

• version
• appName
• environment
• deployedAt

The following fields can be updated:

• fixesVersion
• description

Example request with curl

curl -X POST \
  https://hook.swarmia.com/deployments \
  -H "Authorization: $AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v2.0.6",
    "fixesVersion": "v2.0.5",
    "appName": "frontend",
    "environment": "production",
    "deployedAt": "2022-04-11T05:14:03Z",
    "description": "New description"
  }'

GitHub actions example

Here's an example GitHub actions configuration that sends basic deployment details to Swarmia. This example assumes that your deployment is triggered or executed as a GitHub actions step, and that change failures are manually marked via the Swarmia app.

Make sure to add this step after your deployment step. 

- name: Send deployment to Swarmia
  if: success()
  run: |
    JSON_STRING=$( jq --null-input --compact-output \
      --arg version "${{ github.sha }}" \
      --arg appName "<YOUR_APP>" \
      --arg environment "production" \
      '{"version": $version, "appName": $appName, "environment": $environment}' )

    curl -H "Authorization: ${{ secrets.SWARMIA_DEPLOYMENTS_AUTHORIZATION }}" \
      -H "Content-Type: application/json" \
      -d "$JSON_STRING" \
      https://hook.swarmia.com/deployments

After copying the YAML configuration in your repository, remember to:

1. Add SWARMIA_DEPLOYMENTS_AUTHORIZATION secret to GitHub, containing the correct Authorization header.
2. Change <YOUR_APP> to the relevant app name.