Generate deployments via the API
Deployment API gives you flexibility and a full control of deployment data, including tracking multiple environments.
Last updated
Was this helpful?
Deployment API gives you flexibility and a full control of deployment data, including tracking multiple environments.
Last updated
Was this helpful?
can use the Deployment API as input data.
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.
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).
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.
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.
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).
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.
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
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.
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.
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
Then, you can use the GitHub Actions step below in your workflow.
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.
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 (hello@swarmia.com) if you have any issues.
Read more:
If you are sending deployments from a monorepo, see these .
description (string, optional) string description for the deployment. The description is shown in a tooltip in the table next to the version identifier. Maximum length 2048 characters.
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 .
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 .
This typically occurs for API deployments when the specified commitSha is not a merge commit. You can find more information about merge commits .
When using the , 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.
