Deployments API

Deployments API Benefits

Use our API to get more flexibility and control over how you track your devOps activity.

• See Deploy Time - how long code takes to get deployed once a PR has been merged and include Deploy Time in Change Lead Time calculations

• See how often code is successfully deployed to Production with Deployment Frequency (a key DORA metric)

• Keep track of Deployment Failure Rate

How it works

See here for details on how data received via API is used to calculate Deployment metrics in Multitudes.

Deployments

Send us information about your deployments from any CI/CD tool. We’ll use this to calculate metrics such as Change Lead Time through to deployment and Deployment Frequency (more info on Metrics & Definitions).

Authentication

1. In the Multitudes app, go to Settings > Integrations and click on the “Connect” button in the Deployments API card.

   
2. On the resulting modal, click “Generate Token”.

   
3. After the token has been generated, click "Copy Token" and use it in your API calls (see Step 2 below). You will only see this token once!

   

When you close out of the modal, the Deployments API card will now have a “Configure” button instead of “Connect” (see screenshot at left below). Clicking it will give you options to revoke your token or regenerate a new one, should you need it (see screenshot at right below).

POST a deployment

To tell us about a deployment, make an HTTP POST request to our endpoint with the generated authentication token in the header and required parameters.

You should make one POST per repository being deployed and include the commit SHAs of the merge commit for each PR being deployed. This is particularly important if you are deploying multiple PRs at once or if your PRs are being merged via an intermediary branch.

Note that we include each deployment we receive a POST for in our metric calculations. You may want to only POST deployments to your production environment. See more details here.

Path

https://api.developer.multitudes.co/deployments 

Body parameters

• commitSha string or string[] Required

The SHA-1 value(s) of the commit(s) being deployed. Each value should have a minimum of 7 characters. While this is likely fine for most organizations, you may wish to send us a longer SHA if you’d like more assurance that they will be matched to the correct commit and PR data (see here for more information on the uniqueness of short SHA-1 values).

Commits should all be from the same repository. This will determine how the our repositories filter interacts with charts like Deployment Frequency. If there are commits from different repos in the commit_sha field, we will assume the repository of the first commit in the list.

Commits that are authored by users who are not a Contributor in Multitudes will be filtered out of results. If a deployment has no commits authored by Multitudes contributors, the whole deployment will be filtered out of results as we won't be able to attribute it to a Multitudes contributor nor their team.

If a deployment only has commits authored by bots, these will be included in the grey Organization line only.

• environmentName string Required‍

The environment that this is deploying to. We recommend only sending us deployments to your main production environment for an accurate indicator of Deployment Frequency. We don't filter on environmentName. ‍ If you send us deployments to multiple environments for the same commits, we will take the time of the latest deploy to calculate the Deploy Time (and therefore Change Lead Time) of a matched PR. This is because we assume the PR hasn't been fully released until it has been deployed to all environments.

If you send us deployments with the same commits and environment name, we will dedupe by taking the latest received deployment.

• deployedAt UTC datetime in ISO8601 format

The time of the deployment. Default: the timestamp that the POST request was received by our API

• title string

‍A title to give your deployment for easy identification on our drilldown tables. Default: the commit message of the matched commit with the most recent commit timestamp

• tags string

A custom field for you to add labels (e.g., ["is_fix", "is_failure", "sev1", "product_launch"]). In the future, we plan to support filtering on these labels. Default: none

Sending a Test deployment

When you set up the Deployments API, you can send us a Test Deployment to ensure its working.

To do so, add the following Body parameter: isTest boolean true/false

Any deployments that include the isTest parameter will be excluded from any data analysis. Default: false

Responses

Below is formatted as code, response text, description

• 201, Created successfully , Deploy registered successfully.

• 400, Invalid request , The data is not in the expected format, the response will provide a list of fields that have an issue.

• 401, Unauthorized , API key not valid.

• 403, Forbidden, API key does not have the correct scopes or organisation for this request or has been revoked.

• 500, Internal server error. Please contact [email protected] for more information. An unknown error has occurred, please contact support with the returned request ID for us to investigate.

Examples

curl

--fail-with-body flag to ensure cURL will exit with code 22 on an HTTP failure status code (>=400). Otherwise, you can look for a non-20x status code to detect a failure.

curl --request POST \
  --fail-with-body \
  --url "https://api.developer.multitudes.co/deployments" \
  --header "Content-Type: application/json" \
  --header "Authorization: $MULTITUDES_ACCESS_TOKEN" \
  --data '{"commitSha": "$COMMIT_SHA", "environmentName":"$ENVIRONMENT"}'

With a list of commit SHAs:

curl --request POST \
  --fail-with-body \
  --url "https://api.developer.multitudes.co/deployments" \
  --header "Content-Type: application/json" \
  --header "Authorization: $MULTITUDES_ACCESS_TOKEN" \
  --data '{
   "commitSha": [
       "8750d79cce5f2d137c3f4a34cdd4c9da76c26cfb",
       "561b41361698b579e40f0f9a68491a0e64f48849"
   ],
   "environmentName": "test"
}'

With a list of all SHAs since the last commit to this branch:

This is especially useful if your feature branches are merged to a develop/staging/test branch and then that branch is eventually merged into a "production" branch for deployment.

PREV_DEPLOY=HEAD^1
CURRENT_DEPLOY=HEAD
# get the commit sha's of all commits after the previous deploy to the current deploy
REV_LIST=`git rev-list --ancestry-path $PREV_DEPLOY..$CURRENT_DEPLOY`
# make the rev_list into json
REV_LIST=[\"${REV_LIST//[^a-f0-9]/\", \"}\"]
# post the deployment info with curl
curl --request POST \
  --fail-with-body \
  --url "https://api.developer.multitudes.co/deployments" \
  --header "Content-Type: application/json" \
  --header "Authorization: $MULTITUDES_ACCESS_TOKEN" \
  --data '{
   "commitSha": $REV_LIST,
   "environmentName": "$ENVIRONMENT"
}'

Sending a test deployment:

curl --request POST \
  --fail-with-body \
  --url "https://api.developer.multitudes.co/deployments" \
  --header "Content-Type: application/json" \
  --header "Authorization: $MULTITUDES_ACCESS_TOKEN" \
  --data '{
   "commitSha": "8750d79cce5f2d137c3f4a34cdd4c9da76c26cfb",
   "environmentName": "test",
   "isTest": true
}'

Retrieving deployment data

After sending a deployment through the API, you can verify the transmitted data using our GET endpoint with the generated authentication token in the header.

Path

https://api.developer.multitudes.co/deployments 

Query parameters

• page number

The page number of of the deployments. Default: 1

• pageSize number

The number of deployments to show per page. Maximum is 100. Default: 20

• includeTests boolean true/false

Whether to include deployments with isTest set to true in the response. Default: false E.g. pageSize 20, page 2, would return deployments 21-40.

Responses

Below is formatted as code, response text, description

• 200, OK , Retrieved deploys successfully.

• 401, Unauthorized , API key not valid.

• 403, Forbidden, API key does not have the correct scopes or organisation for this request or has been revoked.

• 500, Internal server error. Please contact [email protected] for more information. An unknown error has occurred, please contact support for us to investigate.

Examples

curl

--fail-with-body flag to ensure cURL will exit with code 22 on an HTTP failure status code (>=400). Otherwise, you can look for a non-20x status code to detect a failure.

curl --request GET \
  --fail-with-body \
  --url "https://api.developer.multitudes.co/deployments" \
  --header "Content-Type: application/json" \
  --header "Authorization: $MULTITUDES_ACCESS_TOKEN"

Including test deployments:

curl --request GET \
  --fail-with-body \
  --url "https://api.developer.multitudes.co/deployments?includeTests=true" \
  --header "Content-Type: application/json" \
  --header "Authorization: $MULTITUDES_ACCESS_TOKEN"

With different page and page size:

curl --request GET \
  --fail-with-body \
  --url "https://api.developer.multitudes.co/deployments?page=2&pageSize=25" \
  --header "Content-Type: application/json" \
  --header "Authorization: $MULTITUDES_ACCESS_TOKEN"

GitHub Actions

Example with a single commit SHA:

jobs:
  log-deployment:
    runs-on: ubuntu-latest
    needs: [ <DEPLOYMENT_JOB> ]
    environment: ${{ inputs.environment }}
    steps:
      - run: |
          curl --request POST \
            --fail-with-body \
            --url "https://api.developer.multitudes.co/deployments" \
            --header "Content-Type: application/json" \
            --header "Authorization: ${{ secrets.MULTITUDES_ACCESS_TOKEN }}" \
            --data '{"commitSha": "${{github.sha}}","environmentName": "${{inputs.environment}}"}'

Example collecting all SHAs since the last commit to this branch:

jobs:
  log-deployment:
    runs-on: ubuntu-latest
    needs: [ <DEPLOYMENT_JOB> ]
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: |
          PREV_DEPLOY=HEAD^1
          CURRENT_DEPLOY=HEAD
          # get the commit sha's of all commits after the previous deploy to the current deploy
          REV_LIST=`git rev-list --ancestry-path $PREV_DEPLOY..$CURRENT_DEPLOY`
          # make the rev_list into json
          REV_LIST=[\"${REV_LIST//[^a-f0-9]/\", \"}\"]
          # post the deploy details        
          curl --request POST \
            --fail-with-body \
            --url "https://api.developer.multitudes.co/deployments" \
            --header "Content-Type: application/json" \
            --header "Authorization: ${{ secrets.MULTITUDES_ACCESS_TOKEN }}" \
            --data "{\"commitSha\": $REV_LIST, \"environmentName\": \"${{inputs.environment}}\"}"

Learn more about Deployments Metrics here