# Generate deployments from GitHub checks

## Configuration

[**Deployments**](https://app.swarmia.com/metrics/deployments) can use Check Runs from [GitHub's Checks API](https://docs.github.com/en/rest/reference/checks) as the input data.

1. [**Start by creating an application**](https://app.swarmia.com/settings/deployments) and giving it a name
2. Select "**GitHub check tracks deploys**" as the **Deployment source**.
3. Select repository
4. Select the check and the branch (or branch prefix) that most accurately represent your production deployment events. You can give this environment a name, although we recommend "production".
5. *Optional:* Add more environments based on the check and the branch name or prefix. This allows you to view deployments from different environments on the [Metrics → DORA → Deployments](https://app.swarmia.com/metrics/dora/deployments) page.
6. Confirm the amount of deployment data to be created, and **Save**

<figure><img src="https://2772466312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMa8uBmGhQgR7MTPq9yh7%2Fuploads%2FOF9yEGnHdGLmVEvtVAWU%2F003560%402x.png?alt=media&#x26;token=6361de61-fef7-4f2f-b87b-6d55b349489c" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Swarmia does not yet support backfilling check deployments from before creating the deployment configuration.
{% endhint %}

## Not using GitHub checks yet?

In order to surface the deployment data on Swarmia, you'll need to ensure that your CI (Continuous Integration) system is properly configured to pass the Checks data to GitHub.

{% hint style="info" %}
You can also use the [**Deployments API**](https://help.swarmia.com/sending-deployment-information-to-swarmia) to pass deployments to Swarmia.
{% endhint %}

Luckily, most modern CI systems offer a productized means of passing this data to GitHub. There are a lot of CI apps directly available on [GitHub's marketplace](https://github.com/marketplace/category/continuous-integration), which means this is likely the best place to start.

Custom implementations can also be created via GitHub's webhooks, which can be configured to exclusively listen to push and PR creation events.

When your CI system of choice has a GitHub app, you'll need to enable each repository to use the said app in the repository settings (Repository > Settings > Integrations).

{% hint style="info" %}
You're likely going to need administrative permissions for any GitHub repository when integrating a CI system to use GitHub checks.
{% endhint %}

## Why my failed GitHub checks are not showing up in Swarmia as deployments?

The failed/succeeded deployment status in Swarmia's DORA/Deployment insights is communicating if a change (= piece of code) that you deployed to production caused a change failure. In other words, if it caused a failure in production that needed a fix in the form of a rollback, forward fix, etc. This information is based on [automatic or manual change failure](https://help.swarmia.com/deployment-insights#about-change-failures) data.

GitHub check conclusion, on the other hand, communicates the status of getting code to production. If a GitHub check has the conclusion `failure`, it means that you failed to deploy code to production, not that you caused a change failure. Because of this, Swarmia only creates deployments for check when they have the conclusion `success`.

## Connecting common CI systems to GitHub

Please refer to your CI provider's documentation to integrate the Check Run data. Below, we go through a high-level overview of some commonly used systems.

### **CircleCI**

For CircleCI, [GitHub Checks are enabled on the CircleCI interface](https://circleci.com/docs/2.0/enable-checks/#to-enable-github-checks). You'll want to ensure you have the [CircleCI app](https://github.com/marketplace/circleci) installed for the GitHub project, the repository configured to use the app, and sufficient access rights both on CircleCI project and the GitHub repository.

#### **Prerequisites**

* You must be using the cloud-hosted version of CircleCI.
* Your CircleCI project must be using Workflows.
* You must be an Admin on your GitHub repository to authorize installation of the CircleCI Checks integration.

### **TravisCI**

TravisCI has a GitHub app which can be found from the Marketplace. You'll want to start by [installing the app](https://github.com/marketplace/travis-ci) and configuring the app for the GitHub repository (Settings > Integrations).

### **Jenkins**

The easiest way to integrate Jenkins checks to GitHub is to use the [GitHub Checks plugin](https://plugins.jenkins.io/github-checks/). However, you first need to [authorize your Jenkins as a GitHub App](https://github.com/jenkinsci/github-branch-source-plugin/blob/master/docs/github-app.adoc)

### **Bamboo**

For Atlassian's Bamboo server, there's an [addon](https://marketplace.atlassian.com/apps/1220795/build-status-for-github) for passing the Check Run data to GitHub. If your version is not compatible with the addon, you'll need to create a GitHub [App](https://docs.github.com/en/rest/reference/apps) to get in order to have API access to create check runs via the [Checks API](https://docs.github.com/en/rest/reference/checks).