Climb the maturity ladder with the Recommended Source Control Track
Estimated Time: 1 hour
Introduction
Is your organization seeking to standardize its repository security & configurations? This tutorial is for you!
It's common for many organizations to ask engineering teams to enforce repository policies. These policies can include branch protection rules, standardizing PR approval settings, and more!
In this tutorial, we'll walk through the available Spotify-provided fact collectors specific to the SCM tool used in your organization. Soundcheck supports all the most popular fact collectors out of the box to ensure your organization can start standardizing its repository controls smoothly & efficiently.
Requirements
- Completed Soundcheck Backend Setup
- Completed Soundcheck Frontend Setup
- Completed one of our supported SCM-specific prerequisites
Understanding the Recommended Settings Track
What is a Track?
Tracks encourage alignment to architectural best practices and standards and are analogous to an organization’s long-term tech health initiatives.
What is a Check?
Checks indicate where the software aligns with or deviates from organizational standards and best practices.
Soundcheck populates a Recommended Source Control track with a set of pre-populated checks on the first startup of Soundcheck. It inspires what a real track & set of checks may look like in the wild.
If you're interested in learning more about the shape of a track or check, we recommend checking out the following documentation for further reading:
Configuring the Recommended Settings Track
Github
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/github/check-pull-request-requires-review.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/github/check-force-pushes-disabled.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/github/check-repository-has-owner.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/github/check-deletions-are-forbidden.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/github/track-recommended-github-settings.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/github/check-admins-must-follow-rules.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/github/check-branch-is-not-locked.yaml
Gitlab
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/gitlab/check-denies_force_push.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/gitlab/check-uses_javascript.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/gitlab/check-code_owner_approval_required.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/gitlab/check-only_allows_merge_if_all_discussions_are_resolved.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/gitlab/check-not_archived.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/gitlab/track-recommended-gitlab-settings-track.yaml
Azure DevOps
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/azure/track-recommended-azure-settings.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/azure/azure-devops-fact-collector.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/azure/check-enforcing-status-checks.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/azure/check-force-pushes-disabled.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/azure/check-deletions-are-forbidden.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/azure/check-repository-has-project.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/azure/check-pull-request-requires-review.yaml
https://21894833.fs1.hubspotusercontent-na1.net/hubfs/21894833/.COM-resources/recommended-source-control-settings-tutorial-files/azure/check-branch-default-main.yaml
NOTE: If you're new to Soundcheck & use GitHub, skip this step! The plugin comes pre-loaded with a Recommended GitHub Settings track for your convenience.
Up above, we provide a track inspired by Spotify's own recommended standards we use for our internal Backstage. Please feel free to download the tracks & checks associated with your organization's SCM.
Ready-to-Go Collector YAML
What is a Collector?
A fact collector collects one or more facts about entities, and Soundcheck can be extended with additional fact collectors. Collectors are responsible for integrating with TPIs or other Backstage plugins to gather information related to Backstage entities in your Software Catalog.
What is a Fact?
Facts represent data related to an entity in your Software Catalog. The data can be formatted in any desired format, defined by the fact collector. Each fact collector will have its fact schema representing what type of facts are returned to the collector.
Initializing the GitHub Fact Collector
Here's an example of the GitHub Fact Collector configuration. The collector YAML will vary slightly based on your SCM as you follow the tutorial.
These files should be copied into your Backstage directory at the following locations at the top of the file, commented out.
# ./packages/backend/src/plugins/soundcheck/collectors/github-fact-collector.yaml
---
frequency:
hours: 1
initialDelay:
seconds: 5
filter:
kind: component
cache:
duration:
hours: 24
collects:
- factName: branch_protections
type: BranchProtections
branch: main
- factName: repository_details
type: RepositoryDetails
# app-config.yaml
soundcheck:
results:
history:
enable: true
retentionTimeInDays: 90
cleanupFrequencyCron: '0 0 0 * * *'
cleanupTimeoutInMinutes: 5
certifications:
history:
enable: true
retentionTimeInDays: 90
cleanupFrequencyCron: '0 0 0 * * *'
cleanupTimeoutInMinutes: 5
collectors:
github:
- $include: ./packages/backend/src/plugins/soundcheck/collectors/github-fact-collector.yaml
Soundcheck scheduling best practices
When you schedule a collector, it collects facts on all entities that match the collector's filter. If the fact for an entity is updated compared to its cached version (or if there is no cached fact, Soundcheck finds all checks that depend on that fact and automatically executes them to produce check results.
When you schedule a check, it executes on all entities that match the check's filter, Soundcheck will request a collection of the required facts on all entities matching that filter if the fact isn't already cached, then execute the check to produce a check result.
Scheduling using collectors is the highly recommended approach. Collector scheduling respects rate-limiting settings whereas check scheduling does not.
Most facts come from a fact collector. The only exceptions to this are the internal-built Catalog facts & Soundcheck certification facts provided natively by the core Soundcheck module. For these facts, users only have the option to schedule checks (which then go fetch relevant facts).
Voilà!
Once the configuration is added, feel free to start Backstage! You'll know you're successful when you visit an entity to see its check results showing pass / fail results in your Soundcheck UI.
Congratulations! You're measuring how well your organization follows repository best practices!
What's next?
Great question! From here, you have a few paths available to you:
- Organizational standards vary. We encourage adopters to use this track as a starting place for adding new facts & checks to enforce technical standards important for their organization. This example provides everything needed to use as inspiration for additional checks & facts.
- This may have inspired ideas for new tracks for other initiatives besides Recommended Source Control best practices. We have other tutorials & other excellent documentation for configuring additional fact collectors for integrations with other important integrations your organization cares about.