Last updated Dec 2, 2024

Integrate Compass with GitHub

What is GitHub?

GitHub is a Git-based code hosting and collaboration tool, built for teams.

Compass currently supports GitHub as a tool to:

  • import components from GitHub repositories to track them in Compass
  • automate component management from an external tool with config-as-code
  • sync component data, such as deployment activity, from GitHub to Compass
  • automatically scan GitHub for API documentation and endpoints, which display on relevant component pages

Integrate Compass with GitHub

To integrate Compass with GitHub, you must first install the GitHub app in Compass. Then, you can connect Compass to Github organization(s) that contain the repositories from where you want to manage the component.

When you integrate an app with Compass, other Compass users can view events and metrics data sent from the app to Compass, even if they don't have access to that data in the underlying app. For example, when you integrate Bitbucket with Compass, someone who doesn't have access to a repository can see the events and metrics related to that repository in Compass. The same applies to data sent from this app to Compass.

Before you begin

  • Ensure that you’re an owner of the GitHub organization(s) you want to connect to. If you are not an owner, the installation process will not finish successfully.
  • Ensure that you’re an admin on your Compass instance.

Perform the integration

To integrate Compass with GitHub:

  1. Select Apps from the top navigation bar in Compass.
  2. Select Install on the GitHub app card. This installs the GitHub app in Compass.
  3. Select Configure on the GitHub app card.
  4. Authorize the GitHub app to access Compass on your behalf if you haven't previously done so.
  5. Select Connect to GitHub.
  6. The Install Atlassian Compass list displays the GitHub organizations that you're a member of. Select an organization to connect with Compass. You must be an owner of the Github organization you choose.
  7. Select Install.

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.

Connect GitHub as an event source to components

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:

To connect a repository to your component:

  1. In GitHub, copy the link to your component’s repository.
  2. Go to your component in Compass.
  3. In the Overview page of your component’s details, add the link in the Repositories section. Learn more about adding links to a component's resources

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(s) connected to your Compass site. The activity feed does not show deployment events from any repositories that are not in the connected GitHub Organization(s).

  • 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.

Disconnect GitHub organization(s) connected with Compass

Compass’s integration with GitHub organization(s) lets you manage your components with configuration as code (config-as-code) by using GitHub as a component management tool. If you want to configure multiple organizations, you can connect multiple GitHub organizations in the GitHub app. If you no longer want to use config-as-code for a given organization, you can disconnect the organization from Compass.

Before you begin

  • Ensure that you’re an admin on your Compass instance.

Once you disconnect a GitHub organization, any managed components in Compass from that GitHub organization 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.

Disconnect organization(s)

To disconnect a GitHub organization from Compass:

  1. In Compass, from the top navigation bar, select Apps.
  2. Select Configure on the GitHub app card.
  3. Select Disconnect organization on the GitHub app card. The GitHub organization is disconnected from Compass while displaying any remaining organizations. If there are no remaining organizations, the page returns to its initial state with no organization connected.

Now you can manage components previously managed via config-as-code from multiple organizations at once through the Compass UI, and you can configure multiple organizations at a time.

Uninstall the GitHub app from Compass

If you no longer want to use GitHub as a component management tool, you can uninstall the GitHub app from Compass.

Before you begin

  • Ensure that you’re an admin on your Compass instance.

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.

Uninstall the GitHub app

To uninstall the GitHub app from Compass:

  1. In Compass, from the top navigation bar, select Apps.
  2. Select Configure on the GitHub app card.
  3. Select Uninstall on the GitHub app card. The GitHub app uninstalls 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 for the organization you just disconnected. At any time, you can again integrate Compass with GitHub to set up config-as-code for component management.

Supported metrics

Learn more about working with metrics in Compass.

The GitHub app for Compass supports the following metrics:

MetricDescriptionHow it's calculated
Build Success RateThe 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 TimeThe 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 FrequencyThe weekly average of times a deployment event to production occurred in the previous four weeks.Deployment events from GitHub Actions.
Open Pull RequestsThe count of currently open pull requests for a component.Pull requests for the default branch currently in the open state.
PR Cycle TimeHow 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.

GitHub environment name mapping

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.

  • production: "production", "prod", "prd", "live"
  • staging: "staging", "stage", "stg", "preprod", "model", "internal"
  • testing: "testing", "test", "tests", "tst", "integration", "integ", "intg", "int", "acceptance", "accept", "acpt", "qa", "qc", "control", "quality", "uat", "sit", "canary"
  • development: "development", "dev", "trunk"

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.

Import components from GitHub

Once you have finished setting up the integration, you can import your repositories from GitHub into Compass as components in the two ways listed below. Learn more about importing from GitHub here.

To import components:

  1. Select Create from the top navigation bar in Compass
  2. Click "Import components" to get started. You can import multiple components at once.

To import components through the GitHub app:

  1. Select Apps from the top navigation bar in Compass.
  2. Select Configure on the GitHub app card.
  3. Click Select repositories to get started. You can import multiple components at once.

Automatic import

By default, the GitHub app for Compass will detect when repositories are created in any connected GitHub organization and automatically create components in Compass for them. The best way to keep your Compass catalog accurate and up-to-date is using automation to make sure all your components are there.

All components created this way will be of type service but you can change that. Compass also knows when you're using a template and takes care not to create duplicate components.

If you want to disable the automatic import feature for any connected organization:

  1. Select Apps from the top navigation bar in Compass.
  2. Select Configure on the GitHub app card.
  3. Toggle Automatic import to off for each connected GitHub organization. Repositories will now need to be manually imported.

Config as code

Optionally, Compass can open a pull request to add a compass.yml file enabling config as code to any components imported with automatic import. Learn more about config as code.

To enable config as code for any automatically imported components:

  1. Select Manage your apps from the Apps navigation menu in Compass.
  2. Select Configure on the GitHub app card.
  3. Toggle Automatic import on for each connected GitHub organization you want to manage with config as code (if not already on).
  4. Toggle Config as code on for each connected GitHub organization you want to manage with config as code.

Troubleshooting

If Compass was installed in your GitHub organization but you don’t see your GitHub organization in Compass, there may have been an issue with the app installation process.

GitHub organizations can only have one instance of Compass installed. Before you proceed with the steps below, confirm that the GitHub organization has not been intentionally connected to another Compass instance.

To uninstall and reinstall the GitHub app, you need both Compass product admin and GitHub organization admin permissions.

Once you are sure that the Compass instance is correct:
  1. From the GitHub admin page for “Atlassian Compass”, select Connect
  2. Select Configure next to your GitHub organization
  3. On the “Atlassian Compass” integration page, find the Danger zone section and select Uninstall
  4. Go back to the GitHub admin page in Compass and select your GitHub organization
  5. Select Install & Authorize
  6. Return to the GitHub admin page and verify that your organization is connected

Monorepos

We recommend you create a component which represents the entire monorepo and then additional components to represent each part of (or the packages/modules within) the monorepo.

The GitHub integration will capture all activity (events, metrics) across the entire monorepo regardless of the path you enter for the repository URL. You can change this behavior by navigating to a component detail page, select more actions (•••), then Component of a monorepo, and enable this setting. This will stop the Bitbucket integration from collecting and processing repository activity for this component. Disabling the setting will connect the component back to GitHub and Compass will backfill activity for the last 28 days.

To get accurate events and metrics for each of the components within a monorepo after enabling this setting, you should use our API:

Enabling the Component of a monorepo setting will delete any existing data (events, metrics) for builds, deployments, and pull requests collected by the GitHub integration for the component.

Creating monorepo components with GraphQL

If you're creating components using the GraphQL API, you can set the isMonorepoProject field to true or false to control the "Component of a monorepo" setting with the createComponent mutation.

Rate this page: