GitHub is Echoes most commonly used integration. Its purpose is to subscribe to events in order to collect information about merged pull requests.
Echoes is packaged as a GitHub App, which comes with many advantages.
The installation flow is managed by GitHub end and gives you freedom to install Echoes on all of your repositories, or selectively on a subset of them.
Permissions are fine-grained, and Echoes will request the following:
Echoes doesn't have access to your repository content when using the GitHub integration. This means that Echoes cannot clone the repository, access the content of a file, read a pull request's changeset, nor list the files modified by a pull request.
If you don't have permissions to install a GitHub App on the target organization, a request will be submitted by GitHub to the organization's administrators for approval. Once approved, this installation will require to be manually linked to your Echoes account for security reasons: send an email to email@example.com and we will take care of it.
How to decide on which repositories to install Echoes or not? The short answer is that there is essentially no downside to installing Echoes on all repositories.
Installing Echoes on a repository has the following effects:
Echoes des not alter previously existing labels, modify any previously existing content, or alter visible attributes of the repository of any way. The only GitHub data Echoes ever writes are the one it has ownership for (i.e., its own created labels and pull request checks).
Additional repositories can be added at any time through GitHub settings. Be aware that the activity on repositories on which Echoes isn't installed won't appear in the reports. Therefore we recommend installing on all repositories (current and future) by default.
Echoes integrates with the GitHub checks API to help developers remember to add the relevant labels to their pull requests.
Echoes checks pull requests have at least one echoes/intent or echoes/initiative label, and optionally one echoes/effort label. The "details" links has useful documentation to help communicating engineers the purpose of these labels.
To avoid creating unnecessary noise for engineers or teams that wouldn't yet be included in Echoes reporting, checks are only run if the author of the pull request belongs to a team within Echoes configuration. For others, the check will be shown as skipped. This is helpful to onboard your organization progressively, or if you have an open source repository with external contributors.
GitHub checks can be disabled on a team-per-team basis through the teams settings.