Generate deployments via the Deployments API

Deployments API gives you flexibility and a full control of deployment data, including tracking multiple environments.

Getting started

Deployment Insights can use the Deployment API as input data.

1. Start by creating an application and giving it a name
2. Select "Send deployment data via the API" as the Deployment source.
3. Read the instructions for sending deployments and get the API token and store it securely
4. Save your deployment configuration.

Authorization

You need to send Authorization header with access token to successfully make the API requests. You'll find your API token and authorization instructions by creating an application deployment that uses the Deployment API as a source (see: Getting started). 

Types of deployments

There are 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.

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 format is JSON and supports the following 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 your app v2.0.5, you might first deploy it
  to a staging environment, and only later to production.
• appName Identifier for the app or system. Used to specify the specific
  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.
• commitSha Optional full sha of the latest commit in the deployment (e.g. "3fc4a317364fa427cfa8238369eb8535aa1d1670"). Used to calculate what commits and pull requests were included in the deployment. It is also used for revert detection, if you have automatic change failure detection enabled for your application.
• repositoryFullName Required if commitSha is given. The repository's full name for the commit (e.g. "octocat/example").

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",
    "commitSha": "3fc4a317364fa427cfa8238369eb8535aa1d1670",
    "repositoryFullName": "octocat/example"
  }'

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 the previous deployment that introduced an
  issue 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",
    "deployedAt": "2022-04-11T02:22:47Z",
    "commitSha": "3fc4a317364fa427cfa8238369eb8535aa1d1670",
    "repositoryFullName": "octocat/example"
  }'

Updating existing deployments

Deployment updates can be used to, for example, mark a previously-posted existing deployment as a fix to another deployment, or to update the description.

When receiving deployments through the API, we default to creating new deployments. It is a valid 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

If this is the case, the following fields can be updated as per the update request's payload:

• 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" \
      --arg commitSha "${{ github.sha }}" \
      --arg repositoryFullName "${{ github.repository }}" \
      '{"version": $version, "appName": $appName, "environment": $environment, "commitSha": $commitSha, "repositoryFullName": $repositoryFullName}' )

    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.

GitHub actions reusable workflow example

This example moves the GitHub actions example above into a reusable workflow that you can use across multiple repositories.

First, copy the reusable workflow below to .github/workflows/swarmia-deployment.yml.

name: Send deployment to Swarmia Deployment API

on:
  workflow_call:
    inputs:
      app-name:
        required: true
        type: string
      environment:
        required: false
        type: string
        default: 'production'
    secrets:
      token:
        required: true

jobs:
  send-deployment-to-swarmia:
    runs-on: ubuntu-latest
    steps:
    - name: Send deployment to Swarmia
      run: |
        JSON_STRING=$( jq --null-input --compact-output \
          --arg version "${{ github.sha }}" \
          --arg appName "${{ inputs.app-name }}" \
          --arg environment "${{ inputs.environment }}" \
          --arg commitSha "${{ github.sha }}" \
          --arg repositoryFullName "${{ github.repository }}" \
          '{"version": $version, "appName": $appName, "environment": $environment, "commitSha": $commitSha, "repositoryFullName": $repositoryFullName}' )

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

Then, you can use the GitHub actions step below in your workflow.

send-deployment-to-swarmia:
    name: Send deployment to Swarmia
    uses: ./.github/workflows/swarmia-deployment.yml
    needs: deploy-production
    with:
      app-name: <YOUR_APP>
      environment: 'production'
    secrets:
      token: ${{ secrets.SWARMIA_DEPLOYMENTS_AUTHORIZATION }}