Generate deployments via the API

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

Getting started

Infrastructure → Deployments can use the Deployment API as input data.

Start by creating an application and giving it a name.
Select "Send deployment data via the API" as the Deployment source.
Read the instructions for sending deployments, get the API token, and store it securely.
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:

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!
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.

Deployments from monorepos

If you are sending deployments from a monorepo, see these docs.

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 (string, 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 (string, required) 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.
environment (string, optional) Identifier for the app's environment. For example, production or staging. If not provided, will be set to the value default.
deployedAt (string, optional) Timestamp in ISO 8601 format. For example, 2022-04- 11T02:22:47Z. Defaults to current time.
description (string, optional) string description for the deployment. The description is shown in a tooltip in the Deployment Insights table next to the version identifier. Maximum length 2048 characters.
commitSha (string, optional) full sha of the latest commit in the deployment (e.g. 3fc4a317364fa427cfa8238369eb8535aa1d1670). Used to calculate which 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 (string, required if commitSha is given) The repository's full name for the commit (e.g. octocat/example).
includedCommitShas (string[], optional) Manually specify which commits this deployment contains instead of calculating the git diff between this and the previous deployment. You will still need to also provide the latest commit in commitSha. Useful for monorepo setups.
filePathFilter (string, optional) Require that all PRs that would be associated with this deployment include changes to a file whose path contains filePathFilter. So for example filePathFilter: "service-1/" would match a PR that contains changes to src/service-1/main.ts. Useful for monorepo setups.

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:

Add SWARMIA_DEPLOYMENTS_AUTHORIZATION secret to GitHub, containing the correct Authorization header.
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 APIon:
  workflow_call:
    inputs:
      app-name:
        required: true
        type: string
      environment:
        required: false
        type: string
        default: 'production'
    secrets:
      token:
        required: truejobs:
  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 }}

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

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

Frequently asked questions

Why can't I see my deployment in Swarmia despite getting a successful API response?

The API call might fail later despite the initial HTTP status code 200 (OK). Our system returns a successful response when it receives the request, but validates the deployment information only later during processing. This maximizes reliability but has the downside of less visibility for you. We're looking into improving the API ergonomics in the future. Meanwhile, please contact our support ([email protected]) if you have any issues.

Why don't my deployments have the right associated PRs?

This typically occurs for API deployments when the specified commitSha is not a merge commit. You can find more information about merge commits on GitHub.

When using the Deployment API, you can provide different fields that would define the deployment. A very important field is the commitSha. When provided, we will automatically associate the related pull requests to the deployment. For instance, if you are sending deployments through the Deployment API when a pull request is merged, and you expect that deployment to contain the merged pull request, then the commitSha provided in the deployment's payload must be the merge commit hash of the expected pull request.

How Swarmia links PRs to deployments

How do I set up deployments in a monorepo?

Generate deployments for monorepos via the API

PreviousGenerate deployments from GitHub checks NextGenerate deployments for monorepos via the API

Last updated 2 months ago

Was this helpful?