> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/organization/configuring-deployments-in-swarmia/generate-deployments-via-the-deployment-api.md). # 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](https://app.swarmia.com/infrastructure/deployments) can use the Deployment API as input data. 1. [Start by creating an application](https://app.swarmia.com/settings/deployments) and giving it a name. 2. Select "**Send deployment data via the API**" as the **Deployment source**. 3. Read the **instructions for sending deployments,** **get the API token,** and store it securely. 4. **Save** your deployment configuration.
## Authorization You need to send the Authorization header with an 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. The token is organization-wide, so treat it as a shared secret and store it in your CI system's secret storage. To rotate it, contact . ## 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 would cause issues when deployed, you wouldn't 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. ### **Deployments from monorepos** If you are sending deployments from a monorepo, see these [docs](https://help.swarmia.com/generate-deployments-for-monorepos). ## Sending a deployment To tell Swarmia about a deployment, make an **HTTP POST** request to **. This can be done from a CI run, deployment script, or even manually, depending on your process. Swarmia validates your payload and returns the result in the response, so a rejected deployment tells you which field was wrong. Linking the deployment to commits and pull requests happens afterwards, once the response has been sent. Send one deployment per request. The request body format is JSON, the maximum body size is 1 MB, and the following fields are supported. ### Required fields * `version` (string or number) Identifier for the version that just got deployed. Depending on the conventions of your organization, app, or team, this might be a semantic version string (e.g. `v2.0.5`), a release tag (e.g. `20220413-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. Maximum length 255 characters, and it can't be blank. * `appName` (string) Identifier for the app or system. Used to specify the specific system of your organization that 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. Maximum length 255 characters. This must match the read-only **API name** shown in [deployment app settings](https://app.swarmia.com/settings/deployments) exactly, including capitalization. ### Optional fields * `deployedAt` (string) Timestamp in ISO 8601 format. For example, `2022-04-11T02:22:47Z`. Maximum length 64 characters. Defaults to current time. * `environment` (string) Identifier for the app's environment. For example, production or staging. Maximum length 128 characters. If not provided, it's set to the value `default`, which isn't counted as a production environment by default. See [environments and DORA metrics](#environments-and-dora-metrics). * `description` (string) String description for the deployment. The description is shown in a tooltip in the [Deployment Insights](https://app.swarmia.com/insights/deployments) table next to the version identifier. Maximum length 4096 characters. * `commitSha` (string) 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](/features/metrics/track-dora-metrics/automatic-change-failure-detection.md) enabled for your application. Must be a **full 40-character SHA-1 or 64-character SHA-256 hash**. Abbreviated SHAs such as `56e8130` are rejected. * `repositoryFullName` (string, required if `commitSha` is given) The repository's full name for the commit (e.g. `octocat/example`). For GitLab, provide the project's full path (e.g. `my-org/my-team/my-project`). Must be a slash-separated path of at least two segments, using only letters, numbers, `_`, `.`, and `-`. Full URLs and bare repository names are rejected. Maximum length 256 characters. * `includedCommitShas` (string\[]) Manually specify which commits this deployment contains instead of calculating the git diff between this and the previous deployment. Each entry must be a full commit SHA, and you will still need to also provide the latest commit in `commitSha` and its `repositoryFullName`. Maximum 10,000 entries. Useful for [monorepo setups](https://help.swarmia.com/generate-deployments-for-monorepos). * `filePathFilters` (string\[]) Require that all PRs that would be associated with this deployment include changes to a file whose path contains one of `filePathFilters` entries. So for example `filePathFilters: ["service-1/", "service-common"]` would match a PR that contains changes to `src/service-1/main.ts`. We currently do not support glob patterns. Maximum 1000 entries, each up to 4096 characters. Useful for [monorepo setups](https://help.swarmia.com/generate-deployments-for-monorepos).\ **Please note:** If `filePathFilters` for the app is already configured (i.e. a value exists), the value of this field will be ignored. You can view and edit the current value in [deployment app settings](https://app.swarmia.com/settings/deployments). {% hint style="info" %} Swarmia automatically creates a new deployment application if you send a deployment via the API with an `appName` that doesn't already exist. {% endhint %} ### Field formatting rules A few validation rules catch people out. Breaking any of them rejects the whole deployment, so it's worth checking these first if a request comes back with an error. * **Omit optional fields instead of sending `null`.** `environment: null` and `repositoryFullName: null` are rejected. Tools that template JSON from unset shell variables often produce these. * **Don't send an empty `includedCommitShas` array.** Omit the field, or send `null`. A script that builds the list dynamically should skip the field when the list comes out empty. * **Strip trailing newlines.** `$(git rev-parse HEAD)` captured into JSON can carry a `\n`, which makes the SHA fail validation. Use `jq` with `--arg` as in the examples below, or `tr -d '\n'`. * **Misspelled fields are ignored, not reported.** A payload with `commitSHA` instead of `commitSha` is accepted, but the deployment is stored without commit information, so it gets no pull requests and no change lead 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", "commitSha": "3fc4a317364fa427cfa8238369eb8535aa1d1670", "repositoryFullName": "octocat/example" }' ``` ## Environments and DORA metrics A deployment only counts toward [DORA metrics](/features/metrics/track-dora-metrics.md) if its environment is one of your [production environments](/settings/organization/configuring-deployments-in-swarmia.md#configuring-production-environments). The catch for API deployments is that **omitting `environment` means the deployment counts toward nothing**. It's stored under the name `default`, which doesn't match the production environment filter, so it's left out of deployment frequency, change lead time, time to deploy, and change failure rate. Environment names are also matched exactly and case-sensitively when Swarmia works out which commits belong to a deployment. `production` and `Production` are tracked as two separate deployment histories for the same app, so pick one spelling and use it consistently. ## 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. Maximum length 255 characters. Swarmia looks for an earlier deployment of the **same app and the same environment** whose `version` matches this string exactly. If it doesn't find one, the fix is recorded but no change failure is registered, and no time to recovery is calculated. Setting `fixesVersion` also turns off [automatic change failure detection](/features/metrics/track-dora-metrics/automatic-change-failure-detection.md) for that 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` {% hint style="warning" %} All four fields must match, and `deployedAt` must match to the exact timestamp. If you leave `deployedAt` out, or generate it from the current time, every request gets a different timestamp, so retrying a failed job creates a second deployment rather than updating the first one. Send an explicit, deterministic `deployedAt`, such as the commit timestamp, if your pipeline retries deployments or you rely on updates. Commit information (`commitSha`, `repositoryFullName`, and `includedCommitShas`) can't be changed this way. To correct a deployment that was sent with the wrong commit, delete it in Swarmia and send it again. {% endhint %} ### **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" }' ``` ## When a deployment doesn't show up If the request came back with an error, the response says which field was rejected. The rules that catch people out most often are an abbreviated or newline-terminated `commitSha`, a `repositoryFullName` that's `null` or isn't a slash-separated path, and an empty `includedCommitShas` array. See [field formatting rules](#field-formatting-rules). If the request succeeded and the deployment still isn't where you expect it: * **It's under a different app than you expected.** `appName` is matched exactly, including capitalization, against the **API name** in [deployment app settings](https://app.swarmia.com/settings/deployments). A mismatch creates a second app rather than returning an error. * **It's missing from DORA metrics.** Its environment probably isn't a production environment. See [environments and DORA metrics](#environments-and-dora-metrics). * **It has no pull requests.** A misspelled field name such as `commitSHA` is ignored rather than rejected, so the deployment is stored without commit information. Commits that Swarmia hasn't synced from your Git provider yet have the same effect until the sync catches up. If none of these explain it, contact . ## 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 "" \ --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 `` 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: environment: 'production' secrets: token: ${{ secrets.SWARMIA_DEPLOYMENTS_AUTHORIZATION }} ``` 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 `` to the relevant app name. ## GitLab CI job example Here's an example of a GitLab CI job configuration that sends basic deployment details to Swarmia. Add the following section to `.gitlab-ci.yml` ``` send-deployment-to-swarmia: stage: deploy image: ubuntu:latest when: on_success script: - apt-get update && apt-get install -y curl jq - | JSON_STRING=$(jq --null-input --compact-output \ --arg version "${CI_COMMIT_SHA}" \ --arg appName "" \ --arg environment "production" \ --arg commitSha "${CI_COMMIT_SHA}" \ --arg repositoryFullName "${CI_PROJECT_PATH}" \ '{"version": $version, "appName": $appName, "environment": $environment, "commitSha": $commitSha, "repositoryFullName": $repositoryFullName}') curl -fsS \ -H "Authorization: ${SWARMIA_DEPLOYMENT_TOKEN}" \ -H "Content-Type: application/json" \ -d "$JSON_STRING" \ https://hook.swarmia.com/deployments ``` ### Alternative: GitLab CI include If you prefer to keep the Swarmia deployment definition in a separate file, save the reusable job below to `.gitlab/ci/swarmia-deployment.yml` and include it from `.gitlab-ci.yml` ``` .swarmia-deployment-notify: image: ubuntu:latest when: on_success script: - apt-get update && apt-get install -y curl jq - | JSON_STRING=$(jq --null-input --compact-output \ --arg version "${CI_COMMIT_SHA}" \ --arg appName "" \ --arg environment "production" \ --arg commitSha "${CI_COMMIT_SHA}" \ --arg repositoryFullName "${CI_PROJECT_PATH}" \ '{"version": $version, "appName": $appName, "environment": $environment, "commitSha": $commitSha, "repositoryFullName": $repositoryFullName}') curl -fsS \ -H "Authorization: ${SWARMIA_DEPLOYMENT_TOKEN}" \ -H "Content-Type: application/json" \ -d "$JSON_STRING" \ https://hook.swarmia.com/deployments ``` {% hint style="info" %} Note the "." in ".swarmia-deployment-notify" to define it as a job template {% endhint %} ``` include: - local: '.gitlab/ci/swarmia-deployment.yml' send-deployment-to-swarmia: extends: .swarmia-deployment-notify stage: deploy ``` After copying the YAML configuration to your GitLab pipeline definition file, remember to: 1. Add `SWARMIA_DEPLOYMENT_TOKEN` CI/CD variable, containing the correct `Authorization` header. 2. Change `` to the relevant app name. ## Frequently asked questions ### **Why can't I see my deployment in Swarmia despite getting a successful API response?** The deployment was accepted, so it's usually stored under a different app than you expect, or left out of the view you're looking at. See [when a deployment doesn't show up](#when-a-deployment-doesnt-show-up). ### **Why is my deployment visible but missing from DORA metrics?** Its environment probably isn't treated as production. See [environments and DORA metrics](#environments-and-dora-metrics). ### **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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). When using the [Deployment API](/settings/organization/configuring-deployments-in-swarmia/generate-deployments-via-the-deployment-api.md), 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. A deployment can also end up with no pull requests when its `commitSha` hasn't been synced from your Git provider yet. Swarmia accepts these deployments so that a sync delay doesn't lose data, but change lead time and time to deploy stay empty until the commit arrives. Read more: {% content-ref url="/pages/50yhOlQIlPdBFMUxAxmc" %} [How Swarmia links PRs to deployments](/features/metrics/track-dora-metrics/how-swarmia-links-prs-to-deployments.md) {% endcontent-ref %} ### **How long does it take for a deployment to appear?** Deployments are processed asynchronously. The deployment itself usually appears within a few minutes, and the metrics derived from it, such as change lead time and change failure rate, can take longer because they depend on commit and pull request data being synced. ### **Can I send deployments for several apps from one repository?** Yes. Send a separate request for each app, using the same `repositoryFullName` and a different `appName`. Use `filePathFilters` or `includedCommitShas` to control which pull requests belong to each app. {% content-ref url="/pages/wDudV4eMechHLjbWszCH" %} [Generate deployments for monorepos via the API](/settings/organization/configuring-deployments-in-swarmia/generate-deployments-via-the-deployment-api/generate-deployments-for-monorepos.md) {% endcontent-ref %} ### **How do I set up deployments in a monorepo?** {% content-ref url="/pages/wDudV4eMechHLjbWszCH" %} [Generate deployments for monorepos via the API](/settings/organization/configuring-deployments-in-swarmia/generate-deployments-via-the-deployment-api/generate-deployments-for-monorepos.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.swarmia.com/settings/organization/configuring-deployments-in-swarmia/generate-deployments-via-the-deployment-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.