Uploading Snapshots
Structure your snapshot directory and upload from CI with sentry-cli.
This feature is available only if you're in the Early Adopter program. Features available to Early Adopters are still in-progress and may have bugs. We recognize the irony.
Snapshots is most effective when part of your CI pipeline. To set up, follow our guide on integrating into CI.
Snapshots works for any platform with a frontend. You can view specific platform examples here. This page covers the general upload structure and metadata schema.
You upload snapshots with the sentry-cli build snapshots command, which takes a directory of images and optional JSON metadata files.
sentry-cli build snapshots <output-dir> \
--auth-token "$SENTRY_AUTH_TOKEN" \
--app-id <app-id> \
--project <project-slug> \
For the full command reference, including auto-detected git metadata and sharding behavior, see Snapshots (CLI). For an end-to-end CI setup, see Integrating Into CI.
Each snapshot consists of two files: a .png image and an optional .json metadata file with the same base name and path. You can optionally organize snapshots into subdirectories. If using subdirectories, the filename property in the Sentry UX will include the subdirectory path.
snapshots/
├── homepage.png
├── homepage.json
├── settings/
│ ├── profile.png
│ ├── profile.json
│ ├── billing.png
│ └── billing.json
Filenames are the identity key for each snapshot. Keep them stable across runs so Sentry can accurately diff head against base.
You can include an optional JSON file to add metadata to each image:
{
"display_name": "Billing Page",
"group": "Settings",
"diff_threshold": 0.01
}
| Field | Type | Description |
|---|---|---|
display_name | string | Human-readable label shown in the comparison. viewer. |
group | string | Groups related snapshots in the UI. sidebar. |
diff_threshold | number | Value from 0.0 to 1.0. Sentry reports the image as changed only when the share of changed pixels is greater than this value. 0.01 ignores changes of 1% or less. |
Snapshots supports the following image formats:
- PNG
- JPEG
For the full sentry-cli build snapshots flag reference, see Snapshots (CLI).
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").