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 with index-store generation enabled, pass --skip-build to reuse its index data. How Periphery locates that data depends on the build system.

Xcode

When reusing a separate Xcode build, enable index-store generation with COMPILER_INDEX_STORE_ENABLE=YES and pass the index store directory produced by that build with --index-store-path.

Xcode writes the index store inside the build’s DerivedData directory. Look in the location specified by -derivedDataPath, or Xcode’s configured DerivedData location if that option was omitted. Pass the index store directory within it, rather than the DerivedData directory itself.

periphery scan --skip-build --index-store-path "<index-store-directory>" --strict

Replace <index-store-directory> with the directory containing that build’s index data.

SwiftPM

Periphery asks SwiftPM where its build products are located and discovers the index data automatically. After swift test, run:

periphery scan --skip-build --strict

Use the same Swift toolchain as the earlier build. If that build used options that affect the build location, such as --configuration or --scratch-path, pass the same options to Periphery after --:

swift test --enable-index-store --configuration release
periphery scan --skip-build --strict -- --configuration release

Use --index-store-path when you need to supply an index store that Periphery cannot discover automatically.

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