Maintainer Annotations let maintainers add context to display alongside Scorecard check results. Annotations can provide users additional information when Scorecard has an incomplete assessment of a project's security practices.

To annotate your repository, create a scorecard.yml file in the root of your repository.

You can also place your annotations in .scorecard.yml or .github/scorecard.yml.

The file structure is as follows:

annotations:
  - checks:
      - binary-artifacts
    reasons:
      - reason: test-data # the binary files are only used for testing
  - checks:
      - dangerous-workflow
    reasons:
      - reason: remediated # the workflow is dangerous but only run under maintainers verification and approval

You can annotate multiple checks at a time:

annotations:
  - checks:
      - binary-artifacts
      - pinned-dependencies
    reasons:
      - reason: test-data # the binary files and files with unpinned dependencies are only used for testing

And also provide multiple annotations for checks:

annotations:
  - checks:
      - binary-artifacts
    reasons:
      - reason: test-data # test.exe is only used for testing 
      - reason: remediated # dependency.exe is needed and it's used but the binary signature is verified

The available checks are the Scorecard checks in lower case e.g. Binary-Artifacts is binary-artifacts.

The annotations are predefined as shown in the table below:

To see the maintainers annotations for each check on Scorecard results, use the --show-annotations option.