In this tutorial we will be using Scorecards for tracking and driving migrations. Recently we have introduced new Data Points for git based Data Sources to extract information from files using regex patterns. In this tutorial we will be building some custom checks using these Data Points to track library and language versions from the contents of metadata files.
Before starting, ensure you have:
An active Harness IDP account, at present IDP is enabled on request so please fill this form to get IDP enabled for you.
Access to your git provider through the connectors in the Admin section, remember to provide API access. Follow the steps mentioned here to create connector once you're in the connector window.
- (Optional) If your catalog-info.yaml does not live at the root of the source code, then ensure the
backstage.io/source-locationannotation appropriately points to the correct source code location.
How to check
Catalog -> Software Component -> Inspect Entity -> Raw YAML
- A registered software component for which you want to track migration.
Understanding Checks in Scorecards
Setting up a Custom Check
- Under Admin section select Scorecards, now go to Checks tab and select Create Custom Check
- Now add Name and Description to the custom check.
Select DataSource and DataPoints
- Select the git provider datasource, for example GitHub along with
extract string from a filedata point to extract the version number.
- Specifying the Branch: If you know the branch name, specify it directly. If not, the system will use the branch from
How to add
backstage.io/source-location is taken from the root of the
catalog-info.yaml in case your services don't live there, you need to add an annotation as mentioned below in your
Location reference that points to the source code of the entity (typically a
Component). Useful when catalog files do not get ingested from the source code repository itself. If the URL points to a folder, it is important that it is suffixed with a
'/' in order for relative path resolution to work consistently.
- Defining the File: Specify the filename with its extension or provide the relative path from the root folder. For example, use .bazelrc, package.json, manifest/Dockerfile. Also you can provide the filename as a regex pattern, example for a file path
/backstage/blob/master/scripts/log-20240105.anyextensionthe regex would be
Specify the Pattern
- Since I'm trying to track to Java Version of my project using the bazelrc file which mentions my java version as
build --java_language_version=17and the corresponding Regex Pattern to be used for the same is
Here, we need to group the string pattern which we want to match using
() for example in the above example we have grouped the number
(\d+) another example is if we would try to match this string
go 1.21 in a go.mod file, the corresponding regex would be
^go\s(\d+\.\d+)$ another regex pattern example for package.json file content
"eslint": "^7.7.0", is
Create a Scorecard
Once the Checks are created, now we need to add them to a new Scorecard.
Go to Scorecards on the left nav in Admin and select Create New Scorecard
Add Name, Description, Owner (same as that of the software component you want to add this scorecard to) and select the Checks you created above to track the migration and publish the Scorecard.
- Now go to the software component in your catalog and under the Scorecards tab you can view the scores, also you can re-run the check to compute score instantaneously.
How does the Score gets computed?
Extracting Data: The system fetches the file, searches for the specified regex pattern within its contents, and then extracts and returns the value.
Result: The system returns a true/false value based on whether the pattern was found in the file or whether a value is the same as desired.
Incorrect File Path:
Ensure the file path is relative to the root folder of the repository.
Pattern Matching Errors:
Verify the accuracy of the pattern you are trying to match. You can use this website for the same, also check for the group
() for the string you're trying to match.
Regularly update the backstage.io/source-location annotation to reflect any changes in the repository structure. Check the regex used for pattern matching.
In this tutorial, we covered how to use Scorecards in Harness IDP for tracking and driving migrations. This tool is incredibly useful for maintaining up-to-date information on various aspects of your software projects, such as dependency versions.