Sending deployment information to Swarmia

Swarmia can ingest deployment information directly from your CI/CD pipeline or from other systems via an 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 previous
deployments.

To enable these insights in Swarmia, please contact us at hello@swarmia.com.

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. Please contact us for your authorization information.

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.

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"
  }'

Marking an existing deployment as a fix

When receiving deployments, we default to creating new deployments (it may well be you deployed the same version twice).

If you want to mark an existing deployment as a fix to another deployment, please include the following parameters to update the existing deployment (and avoid creating a new one):

• version
• appName
• environment
• deployedAt

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"
  }'