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