Integrate Compass with CircleCI

What is CircleCI?

CircleCI is a continuous integration delivery platform that helps development teams release code rapidly and automates the build, test, and deploy process.

Compass currently supports CircleCI as a tool to:

• get Build Success Rate and Build Time metrics
• sync component data, such as deployment build information, from CircleCI to Compass

We’ll show you how to integrate Compass with CircleCI by installing and configuring the CircleCI app in Compass.

Integrate Compass with CircleCI

To integrate Compass with CircleCI, you must first install the CircleCI app in Compass. Then, you connect Compass to your CircleCI organizations using an API token.

Before you begin

Ensure that you’re an admin on:

• Your Compass instance

Perform the integration

To integrate Compass with CircleCI:

Install and configure the CircleCI app

1. In Compass, select Apps from the top navigation bar.
2. On the CircleCI tile, select Install. The CircleCI app installs.
3. On the CircleCI tile, select Configure.
4. If not already done, authorize the CircleCI app to access Compass on your behalf. Select Allow access and follow the on-screen instructions.

• This step appears only once on your Compass instance for each app you install. So, if you've already authorized the CircleCI app before, proceed to the next step.

1. Create a personal API token in CircleCI. Learn how to create a personal API token
2. Paste the API token into the API key field on the CircleCI configuration page.
3. Select Connect account.

The organizations associated with that CircleCI account are connected to Compass.

Add a CircleCI webhook to your projects

Add a CircleCI webhook to any projects you want to track data from with the following information:

• Webhook name: Compass notifications
• Receiver URL (example - see configuration page for actual URL): https://cc07f508-ffa1-48c9-bc02-9c22268985d1.hello.atlassian-dev.net/x1/cVNTbk2t3DH4u6Uta5mI2Pv6eag
• Secret token (example - see configuration page for actual token): ************de9b
• Certificate verification: true
• Events -> Workflow completed: true

Learn more about using webhooks here

Add the Compass Orb to your CircleCI configuration file

An orb is a reusable snippet of code that helps automate repeated processes, accelerates project setup, and makes it easy to integrate with third-party tools. Add the Compass Orb to the CircleCI projects you want data from (the current version number can be found on the Compass Orb page).

1
2
version: 2.1
orbs:
  compass: atlassian-labs/compass@x.y.z

Set up deployment tracking

Add the following code to all of your jobs that run a deployment. The options for environment_type are testing, development, staging, or production.

1
2
workflows:
my-workflow:
  jobs:
    - my-job:
        context:
          - compass-integration-<compass-site-name>
        post-steps:
          - compass/notify_deployment:
              environment_type: production

Start linking components

Go to the components you want to connect to CircleCI data, and add the link for your CircleCI projects to the Project links section(Dashboards or Other links will also work).

Now deployment information for this component will be displayed in the component’s activity feed, and Build Success Rate and Build Time metrics are shown on the component with their metric values. Deployment information will only be included from the time the app is configured forward, Compass doesn’t backfill CircleCI deployment information.

Disconnect the CircleCI account connected with Compass

If you no longer wish to use CircleCI to get component data, you can uninstall the CircleCI app from Compass.

We'll show you how to uninstall the CircleCI app.

Before you begin

• Ensure you're an admin on your Compass instance

Disconnect your CircleCI account

Disconnecting your CircleCI account from Compass removes the stored API token and any environment variables added to your CircleCI organizations.

To uninstall the CircleCI integration:

1. In Compass, select Apps from the top navigation bar.
2. On the CircleCI tile, select Configure.
3. Select Disconnect account.

Your CircleCI account is now disconnected from Compass. You can continue on to uninstall the CircleCI app completely, or enter a new API token to connect to a different CircleCI account.

Uninstall the CircleCI app from compass

You can uninstall the CircleCI app from Compass if you no longer want to get CircleCI component data. Uninstalling the app will result in metrics and deployment activity no longer being pulled into Compass from CircleCI, but existing metrics will not be removed from components and will display the metric value at the time of the app’s uninstall.

Before you begin

• Ensure you’re an admin on your Compass instance
• Disconnect your CircleCI account

Uninstall the CircleCI app from Compass

To uninstall CircleCI integration:

1. In Compass, select Apps from the top navigation bar.
2. On the CircleCI tile, select Configure.
3. Select Uninstall.

The integration is now uninstalled.