GitHub
Purpose
GitHub is Echoes most commonly used integration. Its purpose is to subscribe to events in order to collect information about merged pull requests.
Installation
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:
- Write access to files located at .echoesrc, .github/echoesrc. These Echoes-specific configuration files are reserved for future use, and are the only files that Echoes has permissions to either read or write.
- Read access to members and metadata. Echoes needs to discover members of the organization in order to match with its own view of the organization. This is how Echoes achieves attribution of efforts to the correct team.
- Read and write access to checks, issues, and pull requests. Checks are used to warn engineers when expected labels are missing (see Checking for labels). Write access to issues and pull requests covers use cases where Echoes applies labels itself, for example when tagging contributions from the app, or when inheriting labels from a linked ticket.
Security of your data
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.
Requesting organization administrator approval
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 support@echoeshq.com and we will take care of it.
Selecting repositories
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 will automatically create labels on that repository: one for each configured outcome, one for each configured initiative, and the default "effort" labels.
- Echoes will start checking pull requests for the presence of its labels. However, it only does so when the author belongs to a team which exists within Echoes. See the Checking for labels section below for more details.
- Echoes will receive events for this repository, such as new pull request being opened, or a label being applied to an existing pull request.
Echoes does not modify prior metadata
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.
Checking for labels
Echoes integrates with the GitHub checks API to help developers remember to add the relevant labels to their pull requests. It is disabled by default and can be activated on a team-per-team basis.
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.
Checks are filtered on the author
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 switched on a team-per-team basis through the teams settings.
Making the label check mandatory for merging is possible using GitHub's branch protection rules.