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

Integrate Compass with GitHub

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.

Before you begin

Ensure that you’re an owner of the GitHub organization you want to connect to or work with your organization owner to install this GitHub app.
Ensure that you’re an admin on your Compass instance.

You can connect only one GitHub organization to a Compass instance.

Perform the integration

To integrate Compass with GitHub:

Select Apps from the top navigation bar in Compass.
Select Install on the GitHub app card. This installs the GitHub app in Compass.
Select Configure on the GitHub app card.
Authorize the GitHub app to access Compass on your behalf if you haven't previously done so.
Select Connect to GitHub.
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.
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.

Disconnect the GitHub organization connected with Compass

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.

Before you begin

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

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.

Disconnect the organization

To disconnect a GitHub organization from Compass:

In Compass, from the top navigation bar, select Apps.
Select Configure on the GitHub app card.
Select Disconnect organization on the GitHub app card. The GitHub organization is disconnected from Compass and the page refreshes to its initial state with no organization connected.

Now you can manage the components previously managed via config-as-code from the Compass UI. You can also configure a different GitHub organization.

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:

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