# Deployments API ## Deployments API Benefits Use our API to get more flexibility and control over how you track your devOps activity. * See [`Deploy Time`](https://docs.multitudes.com/metrics-and-definitions/process-metrics/flow-of-work/deploy-time) - how long code takes to get deployed once a PR has been merged and include Deploy Time in [`Change Lead Time`](https://docs.multitudes.com/metrics-and-definitions/process-metrics/flow-of-work/change-lead-time) calculations * See how often code is successfully deployed to Production with [`Deployment Frequency`](https://docs.multitudes.com/metrics-and-definitions/process-metrics/value-delivery/deployment-frequency) ([a key DORA metric](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance)) * Keep track of [`Deployment Failure Rate`](https://docs.multitudes.com/metrics-and-definitions/process-metrics/quality-of-work/deployment-failure-rate) {% hint style="info" %} You can use *either* our Deployments API *or* our [GitHub Actions integration](https://docs.multitudes.com/integrations/github-actions) to provide us with data about deployments. If you already have our GitHub Actions integration configured, generating a token to connect to our Deployments API will override the data from GitHub Actions. {% endhint %} ## How it works [See here for details](https://docs.multitudes.com/metrics-and-definitions/deployment-metrics#if-youre-using-our-deployments-api) 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](https://docs.multitudes.com/metrics-and-definitions)). {% hint style="warning" %} Our data pipeline runs every 6 hours so you may need to wait to see data after you start sending. {% endhint %} ## Authentication * In the Multitudes app, go to [Settings > Integrations](https://app.multitudes.co/teamSettings/integrations) and click on the “Connect” button in the Deployments API card.
* This will take you to the API Keys tab. Click “Generate New Key”.
* In the modal, create an Organization key that has the Deployments write scope
* After the key has been generated, copy it an use as the Bearer token your API calls (see further instructions below). The full key will only be shown once
## Configure Multitudes to use deployments from the API The [Deployment Frequency](https://docs.multitudes.com/metrics-and-definitions/process-metrics/value-delivery/deployment-frequency) chart shows deployments from either GitHub Actions or the deployments you send via the API. To configure which source Multitudes uses, you can set the toggle in the [Organization Settings](https://app.multitudes.co/teamSettings/organizationSettings?section=configure-deployments) page under the Configure deployments section.
## 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. We recommend that you only POST deployments to your production environment; that will match your metrics to the DORA approach, which focuses on deploys to production. See more about [how we calculate Deployment Frequency](https://docs.multitudes.com/metrics-and-definitions/process-metrics/value-delivery/deployment-frequency). ### **Path** ``` https://integrations.multitudes.co/deployment ``` ### **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](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#Short-SHA-1)). Commits should all be from the same repository. This will determine how the our repositories filter interacts with charts like [Deployment Frequency](https://docs.multitudes.com/metrics-and-definitions/process-metrics/value-delivery/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](https://docs.multitudes.com/configuration-and-setup/permissions-and-roles) 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. This field appears in the [Deployment Frequency](https://docs.multitudes.com/metrics-and-definitions/process-metrics/value-delivery/deployment-frequency) drilldown table to help you identify individual deployments. This is particularly useful in a monorepo situation where you might have deployments from one repo going to multiple production environments - you're free to put whatever is most useful for you in there. {% hint style="warning" %} **IMPORTANT** Only POST deployments when you consider something deployed to production. Posting development deployments will cause Change Lead Time to be miscalculated. Anything you send will be displayed and included in metrics as we don't filter out non-production environments. {% endhint %} 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.\ \&#xNAN;*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.\ \&#xNAN;*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.\ \&#xNAN;*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. \ \&#xNAN;*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 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. ```sh curl --request POST \ --fail-with-body \ --url "https://integrations.multitudes.co/deployment" \ --header "Content-Type: application/json" \ --header "Authorization: $MULTITUDES_API_KEY" \ --data '{"commitSha": "$COMMIT_SHA", "environmentName":"$ENVIRONMENT"}' ``` With a list of commit SHAs: ```sh curl --request POST \ --fail-with-body \ --url "https://integrations.multitudes.co/deployment" \ --header "Content-Type: application/json" \ --header "Authorization: $MULTITUDES_API_KEY" \ --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. ```shell 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://integrations.multitudes.co/deployment" \ --header "Content-Type: application/json" \ --header "Authorization: $MULTITUDES_API_KEY" \ --data '{ "commitSha": $REV_LIST, "environmentName": "$ENVIRONMENT" }' ``` Sending a test deployment: ```sh curl --request POST \ --fail-with-body \ --url "https://integrations.multitudes.co/deployment" \ --header "Content-Type: application/json" \ --header "Authorization: $MULTITUDES_API_KEY" \ --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://integrations.multitudes.co/deployment ``` ### **Query parameters** * `page` *number* The page number of of the deployments.\ \&#xNAN;*Default: 1*
* `pageSize` *number* The number of deployments to show per page. Maximum is 100.\ \&#xNAN;*Default: 20*
* `includeTests` *boolean true/false* Whether to include deployments with `isTest` set to `true` in the response.\ \&#xNAN;*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 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. ```sh curl --request GET \ --fail-with-body \ --url "https://integrations.multitudes.co/deployment" \ --header "Content-Type: application/json" \ --header "Authorization: $MULTITUDES_API_KEY" ``` Including test deployments: ```sh curl --request GET \ --fail-with-body \ --url "https://integrations.multitudes.co/deployment?includeTests=true" \ --header "Content-Type: application/json" \ --header "Authorization: $MULTITUDES_API_KEY" ``` With different page and page size: ```sh curl --request GET \ --fail-with-body \ --url "https://integrations.multitudes.co/deployment?page=2&pageSize=25" \ --header "Content-Type: application/json" \ --header "Authorization: $MULTITUDES_API_KEY" ``` ## GitHub Actions Example with a single commit SHA: ```sh jobs: log-deployment: runs-on: ubuntu-latest needs: [ ] environment: ${{ inputs.environment }} steps: - run: | curl --request POST \ --fail-with-body \ --url "hhttps://integrations.multitudes.co/deployment" \ --header "Content-Type: application/json" \ --header "Authorization: ${{ secrets.MULTITUDES_API_KEY }}" \ --data '{"commitSha": "${{github.sha}}","environmentName": "${{inputs.environment}}"}' ``` Example collecting all SHAs since the last commit to this branch: ```sh jobs: log-deployment: runs-on: ubuntu-latest needs: [ ] 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://integrations.multitudes.co/deployment" \ --header "Content-Type: application/json" \ --header "Authorization: ${{ secrets.MULTITUDES_API_KEY }}" \ --data "{\"commitSha\": $REV_LIST, \"environmentName\": \"${{inputs.environment}}\"}" ``` ## Learn more about Deployments Metrics [here](https://docs.multitudes.com/metrics-and-definitions/deployment-metrics)