Rate this page:
GitHub is a Git-based code hosting and collaboration tool, built for teams.
Compass currently supports GitHub as a tool to:
To integrate Compass with GitHub, you must first install the GitHub app in Compass. Then, you connect Compass to the Github organization that contains the repositories from where you want to manage the component.
You can connect only one GitHub organization to a Compass instance.
To integrate Compass with GitHub:
Now you can manage components from the repositories within the connected GitHub organization by setting up configuration as code (config-as-code) for your components. Learn how to manage components via config-as-code
Personal GitHub user accounts can’t be connected to Compass. This app can only be installed for GitHub organizations and enterprise accounts.
The GitHub app for Compass collects events to display on the Compass Activity Feed and automatically calculate certain metrics for your components. The following events are collected when you connect a GitHub repository to your component:
| Event | How |
|---|---|
| Deployment | GitHub Actions deployments using a GitHub Environment name that maps to Production or Staging |
| Build | GitHub Actions builds on the default branch of the connected repository |
To connect a repository to your component:
Events will begin to appear on the activity feed and metrics will begin to calculate on the component details page.
Take a note of these additional points:
A component's deployment activity appears in Compass only if you've connected the event source to the component and there has been at least one deployment in your component’s production or staging type environment within the last 28 days.
The activity feed also shows deployment events from a component's upstream dependencies if you've connected event sources to those components (i.e. added a repository link). The deployment events from your component’s dependencies appear alongside the deployment events from your component.
You can add links to any repositories from the GitHub Organization connected to your Compass site. The activity feed does not show deployment events from any repositories that are not in the connected GitHub Organization.
Build events on the default branch of the repository will not show up on the activity feed but they will be collected and used to calculate certain metrics for your component.
Compass’s integration with a GitHub organization lets you manage your components with configuration as code (config-as-code) by using GitHub as a component management tool. However, if you want to configure a different workspace or no longer want to use config-as-code, you can disconnect your current GitHub organization from Compass.
Once you disconnect a GitHub organization, any managed components in Compass are disconnected and will no longer be synced with GitHub. Don’t worry, the components remain in Compass and you can manage them via the Compass UI.
To disconnect a GitHub organization from Compass:
Now you can manage the components previously managed via config-as-code from the Compass UI. You can also configure a different GitHub organization.
If you no longer want to use GitHub as a component management tool, you can uninstall the GitHub app from Compass.
Once you uninstall the GitHub app, any managed components in Compass are disconnected and will no longer be synced with GitHub. Don’t worry, the components remain in Compass and you can manage them via the Compass UI.
To uninstall the GitHub app from Compass:
Now your GitHub-managed components will no longer be managed by any existing compass.yml files and can be modified and updated via the Compass UI. At any time, you can again integrate Compass with GitHub to set up config-as-code for component management.
Learn more about working with metrics in Compass.
The GitHub app for Compass supports the following metrics:
| Metric | Description | How it's calculated |
|---|---|---|
| Build Success Rate | The ratio of build events for this component that were successful compared to all build events (including failed, timed out, etc.). Only the last 25 build events are evaluated. | Build events on the default branch. |
| Build Time | The average amount of time it took for a build event to finish over the last ten successful build events. | Build events on the default branch. |
| Deployment Frequency | The weekly average of times a deployment event to production occurred in the previous four weeks. | Deployment events from GitHub Actions. |
| Open Pull Requests | The count of currently open pull requests for a component. | Pull requests for the default branch currently in the open state. |
| PR Cycle Time | How long it took on average for a Pull Request to go from ‘open’ to ‘merged’ over the last ten pull requests. | Pull request open and close events for the default branch. |
The GitHub app for Compass evaluates the name of your GitHub Environment for all deployment events and uses a mapping to determine what environment type (Production, Staging, etc.) it falls into. We look for the presence of the below words within the name of the environment to determine the type.
In the case that an environment name matches more than one type, we use the order shown above to determine the mapping. For example, if your environment is named "dev-prod" we would map it to Production.
Once you have finished setting up the integration, you can import your repositories from GitHub into Compass as components. Simply select Create from the top navigation bar in Compass and then choose "Import components" to get started. Learn more about importing from GitHub here.
Rate this page: