Continuous Integration

CI

Create an access token in the Periphery account area, save it as a masked secret in your CI provider, and expose it only to the scan step as PERIPHERY_TOKEN:

env:
  PERIPHERY_TOKEN: ${{ secrets.PERIPHERY_TOKEN }}
steps:
  - run: periphery scan --strict

Treat the access token as a secret and expose it only to trusted jobs, never to unreviewed fork pull requests. CI scans require network access to validate it.

See Authentication for the other authentication mechanisms.

Skipping the Build

If the pipeline has already built the project, pass --skip-build and use --index-store-path to point Periphery to the generated index store.

Xcode

The index store generated by xcodebuild exists in DerivedData at a location dependent on your project, e.g., ~/Library/Developer/Xcode/DerivedData/YourProject-abc123/Index/DataStore. For Xcode 14 and later, the Index directory can be found as Index.noindex, which suppresses Spotlight indexing.

SwiftPM

After swift test, Periphery automatically uses .build/debug/index/store. Pass --index-store-path only when the index store is elsewhere.

Exit Status

By default Periphery exits with a zero status even when it reports results, leaving it to your pipeline to decide what to do with them. Pass --strict to exit with a non-zero status whenever any results are reported:

periphery scan --strict

On an established codebase, --strict will exit with a non-zero status until every existing result is addressed. To narrow this to results introduced from now on, record the existing ones in a baseline and pass it alongside --strict:

periphery scan --baseline baseline.json --strict

Output Formats

The --format option controls how results are formatted. Several formats exist to integrate with the tools that consume them:

Format	Description
`xcode`	The default. Human-readable, and parsed by Xcode when used in a build phase.
`github-actions`	Workflow commands that annotate the relevant lines in the GitHub Actions UI. Must be used with `--relative-results`.
`github-markdown`	A Markdown table, suitable for posting as a pull request comment or job summary.
`gitlab-codequality`	GitLab Code Quality report, displayed in the merge request widget.
`checkstyle`	Checkstyle XML, understood by many CI and code review tools.
`codeclimate`	Code Climate JSON.
`csv`	Comma-separated values.
`json`	Structured JSON, for consumption by your own tooling.
`agent-prompt`	A structured prompt for AI-assisted result removal.

Results are written to stdout. To write them to a file instead, for example to upload as a build artifact or feed into another job, use --write-results:

periphery scan --format gitlab-codequality --write-results gl-code-quality-report.json