About the integration

Code deployments are a key source of change Sleuth needs to do its job. Once a code deployment is integrated as a change of source, Sleuth immediately begins its analysis, looking at your commit history, number of authors, deploy frequency, size of commits, and other data to give you a full picture of how you and your team are managing your project's codebase. You'll instantly see the Trend Graph come to life with a complete snapshot that gives you the information you need to start deploying faster.

Integrating GitHub with Sleuth is simple. If you're setting connecting to a personal GitHub repo, you just need your credentials. If you're part of a GitHub organization and aren't the owner, you will need permission to allow Sleuth to connect to the repo (after you connect you'll be able to select individual private or public repositories).

You can connect as many repositories to a project as you'd like; be sure to name them accordingly in Sleuth. You will also be able to tell Sleuth whether it should manually register each deploy or automatically create deploys for every push to or tag on branch; it's completely up to you. This setting can be changed at any time. Additionally, you can configure your target branch to lock if it contains unreleased code.

Check out the Bitbucket, GitLab, Jira, or Clubhouse integration pages if you'd like to track your issues using those tools instead of or in addition to GitHub.

Setting up the integration

To set up the Sleuth GitHub integration:

  1. Click Integrations in the left sidebar, then click Change Sources.

  2. In the GitHub tile, click enable.

  3. Sign in to your GitHub account. If enabled, enter your 2FA code and click Verify. Don't worry, you'll select the GitHub repo to connect to your Sleuth project later.

  4. Upon successful integration, you'll see GitHub enabled (Connected as <GitHub user account>) displayed in the GitHub tile. You'll next configure the code deployment to connect your repo to a project.

Configuring the integration

You now need to add a GitHub repo to a Sleuth project. This source of change is the repo the configured Sleuth project will monitor and report in the Dashboard on each and every deploy you make to that repo, along with any other change sources you have connected to your project.

To configure the GitHub integration:

  1. After step #4 above, you will be taken back to the GitHub integration tile. On the GitHub tile, click the Add code deployment dropdown.

  2. Select the Sleuth project you wish to add a chance source to from the dropdown list.

  3. In the Add a new Code Deployment change source screen, you must configure which code repo and branch to monitor; give the code deployment a name; select the deploy tracking type; and tell Sleuth whether to lock the target branch if it has unreleased code.

Advanced Settings

The preferences in Advanced Settings allow you to control the flow of data that are generated by a deploy. You can control whether a deploy affects your project's health, shows up in notifications, or is included in the project dashboard.

All settings are on (checked) by default. However, there might be some code that you don't want affecting your frequency graph, or a change source points to a staging version of your codebase that contains fragile code, which you don't want affecting your repo's health report.

For example, Sleuth Documentation is a public Sleuth repo (sleuth-gitbook-docs). However, we have disabled Collect Impact on Deploy for that particular repo. Although we treat documentation as code (our documentation is sourced in Markdown), the impact of deploying documentation shouldn't impact the overall health reports that Sleuth generates for the top-level repo. To put it another way: Documentation commits and PRs shouldn't bring down the application.

The preferences available in Advanced Settings are:

Automatically lock when the target branch has unreleased code 🔒

With this option selected, Sleuth will lock a deployment by adding a status check on pull requests that target the deployment branch.

This lock behavior is equivalent to pressing the Lock button on the dashboard. You can read more about locking here.

Lock button on the dashboard

Notify in Slack

With Notify in Slack checked, all activity in this change source will generate a Slack notification in accordance with any project- and organization-level Slack notification preferences that have already been set.

Collect Impact on Deploy 📏

With Collect Impact on Deploy checked, any impact measurements generated by this change of source will be applied to your project's collective health metrics.

Include in Project Dashboard 📊

With Include in Project Dashboard checked, all the deploys for this change source will be included in the project dashboard and frequency graph.

Removing the integration

If you wish to dissolve the GitHub integration for the organization:

  1. Click on Integrations in the left sidebar, then on Change Sources.

  2. In the GitHub integration card, click disable. The message GitHub disabled is displayed in the GitHub integration card once the integration is dissolved.

The GitHub integration is disconnected and no longer available to any projects within that organization.