Using Shepherd#

Shepherd stores the results of Psalm runs from CI for public GitHub projects. It shows the type coverage history of your default branch at https://shepherd.dev/github/{owner}/{repo} (for example vimeo/psalm) and serves badges for your README.

Getting started#

Add --shepherd to the Psalm command that runs in CI on your default branch:

./vendor/bin/psalm --shepherd

Setting the environment variable PSALM_SHEPHERD=1 does the same. Psalm prints Results sent to Shepherd (shepherd.dev) when the report was accepted. A failed upload never changes Psalm's exit status.

Psalm detects GitHub Actions and other popular CI services, and elsewhere in CI uses the GitHub remote of the checkout. Outside CI, or without a GitHub remote, nothing is sent and Psalm warns Results not sent to Shepherd: no CI service with a GitHub repository detected.

For pull requests, Shepherd also comments on the changed lines where Psalm finds errors, when it can access the repository.

Badges#

[![Psalm type coverage](https://shepherd.dev/github/{owner}/{repo}/coverage.svg)](https://shepherd.dev/github/{owner}/{repo})
[![Psalm level](https://shepherd.dev/github/{owner}/{repo}/level.svg)](https://shepherd.dev/github/{owner}/{repo})

Type coverage is the share of expressions whose inferred type is not mixed, the number in Psalm's summary line.

What is sent#

One JSON POST request at the end of the run, with:

  • the CI build and the last commit, including the names and emails of its author and committer
  • every issue of severity error, with its file path and the source code snippet around it
  • the type coverage counts, your error level, and the versions of Psalm and the PHP parser

Because of the code snippets, don't use --shepherd for code that must not leave your servers. Without --shepherd (or PSALM_SHEPHERD) Psalm sends nothing.

Sending reports to your own endpoint#

Pass a URL instead, and Psalm posts the same JSON there:

./vendor/bin/psalm --shepherd=https://example.com/psalm-report

Psalm posts to exactly that URL, and adds https:// when the value has no scheme.