Generate deployments for monorepos via the API

How to setup the Swarmia deployments API to track deployments from monorepos

Swarmia supports tracking deployments from monorepos (repositories that contain code for multiple applications that are deployed separately) with some additional setup. For this use case, you will need to use the deployments API.

With monorepos, the challenge is in determining which commits (and thus pull requests) belong to which deployment apps. The deployments API provides two ways for this.

Option 1: Differentiate based on which files changed

The deployments API supports filtering associated PRs based on which files they touch via the filePathFilter field. This can be a good approach if your monorepo has a separate folder for each service. For example, let's say that you have a service defined in services/service-1.

When this service is deployed, you would send a deployment to the deployments API with these fields:

"appName": "monorepo/service-1"
"filePathFilter": "service-1/"
"commitSha": "fc24ab8620f41a0ece6541004f1b4e610bc5767b"

We will then look up all the commits between this new deployment and the previous deployment of the same app (based on the commitSha fields). We will find PRs associated with the commits, and then we will filter the PRs based on the filePathFilter so that only PRs that include changes to service-1/ will be included in the deployment.

As a result, PRs from other services in the monorepo will be ignored and your DORA metrics will be tracked correctly.

It is Important to note that the filePathFilter field expects exactly one path, i.e. multiple paths are not supported. We also do not currently support glob patterns for this field. If your app is built using several shared projects and/or spread out over multiple folders in a complex manner you will have to resort to the second option described below.

See the full docs for filePathFilter here.

Option 2: Tell us which commits were deployed

If you need even more granular control than what filePathFilter provides, you can use your own logic to determine which commits (and thus pull requests) should be included in the deployment of the service.

For this you would send us data like this

"appName": "monorepo/service-1"
"commitSha": "fc24ab8620f41a0ece6541004f1b4e610bc5767b"
"includedCommitShas": [
  'fc24ab8620f41a0ece6541004f1b4e610bc5767b',
  '9f08ee13c1ca9fb4ac9635290ab754f734d4c7f2',
  '83a129c486d70d2ae855a7b69110e26649d2ed98'
]

We will then use the includedCommitShas to determine which pull requests should be included in this deployment.

You can also use includedCommitShas in combination with filePathFilter if you for some reason need to.

See the full docs for includedCommitShas here.

For the pull request detection to work, it is required that you include the "merge commit hash" of each deployed pull request in the list of included commits. You can find the merge commit hash from the GitHub UI (see screenshot below)