Create and apply scorecards

In Compass, you can create scorecards to measure the health of your components based on your unique requirements.

What are scorecards?

Scorecards in Compass are a set of criteria that you can apply to a component to measure its health. Each criterion, such as adding a component owner team or adding documentation, has a weight associated with it. All criteria add up to 100% completion, and the current percentage based on the completed criteria represents the score of the component.

Scorecards provide you with strong guidance to cultivate behavior that improves your organization's DevOps practices. They offer you a framework to ensure your software components are healthy and teams are following the recommended best practices. Scorecards not only show a component's health but also indicate the areas that need improvement.

Creating your own scorecards enables you to:

• define company-wide standards and policies to ensure that all teams are aiming for the same standards

• define team-level standards to ensure they follow their own best practices, in addition to the company-wide standards

Create a scorecard

Before you begin

• If your site uses a restricted permission policy, you must be the owner of the scorecard you're changing or a product admin.

• Understand the different methods of applying scorecards so that you can apply scorecards using a method that makes sense for your team and the criteria you want to enforce on your components

Create a scorecard from the scorecard library

You can create a scorecard from the scorecard library or from scratch.

To create a scorecard from the scorecard library:

1. In Compass, select Health from the top navigation.

2. Select Create scorecard.

3. Select a library scorecard.

4. Enter the scorecard's Name.

5. To edit the scorecard's application model and criteria, select Edit. Otherwise, select Create.

Library scorecards

The library includes templates for getting started with scorecards, including Component readiness and DevOps health. More will be added over time.

Component readiness scorecard

The component readiness scorecard measures how ready your components are for use in a production environment.

The scorecard has the following criteria and weight for each criterion:

DevOps health scorecard

The DevOps health scorecard helps your team measure the key information and metrics associated with high-performing development teams.

The scorecard has the following criteria and weight for each criterion:

Create a scorecard from scratch

To create a scorecard from scratch:

1. In Compass, select Health from the top navigation.

2. Select Create scorecard.

3. Select Create from scratch.

4. Enter the scorecard’s Name and Description.

5. Select an Owner. Start typing a name and select the user from the list.

   • An owner is someone who is an expert in the subject area and can be the point of contact. Adding an owner is optional, but we recommend you add one.

6. Select a Component type.

   • The scorecard becomes available for the components of this type.

7. Choose how you want this scorecard applied:

   • To all components of a selected type

   • Manually to individual components

   • By a component label

8. If you selected to apply the scorecard using a component label, search and select a component label from the dropdown menu that appears.

9. Select Next.

10. Under Criteria, select a criterion from the list and enter a percentage that reflects its importance.

    • You must add at least one criterion. The sum of the percentages for all criteria must be 100%.

11. If you need to add another criterion, select Add criterion. Then select a criterion and enter its percentage.

12. Select Create.

If the scorecard is applied to all components of a selected type, Compass implicitly applies it to all components with a matching component type that you set when you created the scorecard. Scorecards applied via component label are also automatically applied, matching components with that label. A scorecard set to be applied manually can now be applied to individual components from their details page.

Publish a scorecard

All scorecards are created as drafts. To view scorecard drafts, select Health from the top navigation in Compass. Scroll down to the list of scorecards. You can sort or filter by State.

To publish a draft scorecard:

1. Open the scorecard and find the Publish button at the top right of the screen.

2. Select Publish.

You may see a warning if you have components that aren’t receiving data required for this scorecard. We recommend completing setup before publishing, but you can still publish without completing data connection if desired.

Delete a scorecard

You can delete scorecards that you no longer want to use.

To delete a scorecard:

1. In Compass, select Health from the top navigation.

2. Locate the scorecard on the Scorecards page then select Delete on it.

3. Select Delete on the confirmation dialog. The scorecard no longer applies to any associated components and no longer exists in Compass.

Methods of applying scorecards

You choose the method of applying the scorecard when you create a scorecard using the field How should this scorecard be applied?

Scorecards in Compass can be applied using one of the following methods:

All selected type(s) of components

This method allows you to apply scorecards to all components of selected type(s), where Compass implicitly applies it to all components with a matching component type that you set when you created the scorecard.

Use this method to apply organization-wide criteria to components and ensure that all teams are following the same operational best practices.

Individual selected types of components

This method is a manual way to apply scorecards, where a component’s type matches the component type that you set in the scorecard’s settings. These scorecards are not mandatory but are the ones that your organization recommends the teams use for all applicable components.

Use this method to apply criteria defined by cross-product or platform teams, such as SRE, security, or DevOps, to components of a particular type.

By a component label

This method of applying scorecards is based on component labels, where a component’s type and component label matches the component type and label that you set when you created the scorecard. These scorecards are not mandatory across the organization, but you can use them for specific components as per your needs.

Use this method to bulk apply scorecards to components of selected type(s) in a more granular way, or apply using labels that match your team or organization structure, categorization, or specific groups of people.

By a component tier

This method of applying scorecards is based on component tier, where a component's type and tier match the type and tier that you set when you created the scorecard. These scorecards are not mandatory across the organization, but you can use them for specific components as per your needs.

Use this method to bulk apply scorecards to components of selected type(s) in a more granular way, or apply using tiers that match your team's prioritization or importance of component(s).

Use regular expressions in scorecard criteria

Use regular expressions (regex) in scorecard criteria to set up policies that specific links be added to components.

A scorecard criterion with regex validation compares the links of the particular type on a component with the regex you provide. The criterion is met when at least one link or its display text matches the regex.

Example

Suppose you want to set up a policy that every service component has a documentation link to a disaster recovery plan. In that case, you can add a scorecard criterion for the Documentation field with regex as \bdisaster\b.*\brecovery\b. This criterion passes when two separate words — disaster and recovery — case-insensitive, but in that order, are part of a documentation link or its display text.

Apply or remove scorecards

Before you begin

• If your site uses a restricted permission policy, you must be the owner of the scorecard you're changing or a product admin.

You can apply scorecards using a few different methods in Compass:

1. Manually (default)

2. Automatically (via filters)

After being applied to a component, the scorecard appears in the Scorecards section. It shows the component’s score based on the completed criteria. You can select the scorecard to view the scorecard details.

You can then review the unmet criteria and take actions to fulfill those criteria. Learn how to update the component’s score

All scorecards are created as drafts. You can apply a draft scorecard to components using any method, but the scorecard won’t be visible on component overviews or send notifications until it is published.

Manually apply a scorecard to a component

To manually apply a scorecard to individual components:

1. Go to the component's Overview page in Compass.

2. Select + Apply scorecard under the Scorecards section.

   • If there aren't any scorecards applied to the component yet, select the empty field under the Scorecards section.

3. Select the Choose a scorecard dropdown to view scorecards or start typing to search and select an applicable scorecard.

   • A scorecard becomes applicable to a component when the component type(s) that are set in the scorecard’s settings matches your component's type.

4. Select Apply.

Remove a manually applied scorecard from a component

To remove a scorecard applied manually to individual components:

1. Go to the component's Scorecards page in Compass.

2. Hover over the scorecard you want to remove from the component.

3. Select More actions (), then Remove.

4. Select Remove on the confirmation dialog to confirm your action.

Automatically apply a scorecard to a component using filters

Automatic application can be set to apply based on these filters:

• Component type (required)

• Label

• Tier

• Team

If you use multiple filters, they will be ANDed together.

To automatically apply scorecards to components:

1. When creating a scorecard, fill out required fields and select Automatically under Apply scorecard.

2. Select a component type filter first. Decide which component type this scorecard should apply to.

3. If you want to apply the scorecard more specifically, select + Add filter for as many filters you want to apply scorecards by from the options listed above. As you select filters, the number of components that will have this scorecard applied is shown.

4. If you want to allow this scorecard to be deactivated from select components manually, check the box in the Deactivation settings section.

5. When you're satisfied with your settings, select Next and finish creating your scorecard.

Deactivate an automatically applied scorecard for a component

Each automatically applied scorecard has an option to allow the scorecard to be deactivated from select components manually. Enabling this option gives component owners more control over the scorecards that should apply to their components.

To deactivate a scorecard:

1. Go to the component's Scorecards page in Compass.

2. Hover over the scorecard you want to deactivate.

3. Select the More actions icon (), then Deactivate.

4. Select Confirm on the confirmation dialog to confirm your action.

To reapply a deactivated scorecard:

1. Go to the component's Scorecards page in Compass.

2. Select the Inactive tab.

3. Select the deactivated scorecard you want to activate.

4. In the scorecard drawer, select Reapply scorecard.