diff --git a/docs/product/snapshots/index.mdx b/docs/product/snapshots/index.mdx index 913878e394e66..3503047721999 100644 --- a/docs/product/snapshots/index.mdx +++ b/docs/product/snapshots/index.mdx @@ -16,7 +16,7 @@ TODO: Arcade Walkthrough (1. status check showing diff, 2. click into sentry to 1. **Generate snapshots** — Your CI job produces screenshots however you like: Playwright, Paparazzi, or any tool that outputs PNGs 2. **Upload to Sentry** — `sentry-cli` uploads the snapshot directory to Sentry 3. **Sentry diffs against the baseline** — Sentry compares images against corresponding base build (TODO: link to section explaining automated comparisons). With Sentry, you do not have to manage "Golden" images and everything is determined via git metadata. -4. **Results post to your PR** — Snapshot results post to your PR\*. You can configure settings(TODO: link to settings) to control status check and comment behavior. +4. **Results post to your PR** — Snapshot results post to your PR\* via a GitHub status check. See [Integrating Into CI](/product/snapshots/integrating-into-ci/) for setup. You can configure settings(TODO: link to settings) to control status check and comment behavior. 5. **Review and approve** — View snapshot results on the Sentry UI. If the Snapshot "failed" you can approve it from either the PR or the Sentry UI. \*Note: Snapshots EA only supports Github diff --git a/docs/product/snapshots/integrating-into-ci.mdx b/docs/product/snapshots/integrating-into-ci.mdx new file mode 100644 index 0000000000000..0d05e00d92b37 --- /dev/null +++ b/docs/product/snapshots/integrating-into-ci.mdx @@ -0,0 +1,84 @@ +--- +title: Integrating Into CI +sidebar_order: 15 +description: Set up Snapshots in CI to receive automated visual diff status checks on every pull request. +--- + + + + + +## GitHub + +The GitHub integration brings Snapshots directly into your pull request workflow by adding status checks. This alerts reviewers to any visual changes a pull request introduces, and requires approval before the check passes. + +Snapshots works by comparing a head vs. base build, similar to how code review compares your new code to the baseline code. + +### Installation + +1. Install the Sentry GitHub App by following the installation instructions in the [GitHub integration documentation](/organization/integrations/source-code-mgmt/github/). + + a. If you have previously installed the Sentry App, ensure you have accepted the latest permissions in order to receive Status Checks. + +2. Generate snapshots in your build using the tool that fits your platform. Common options include: + + - Playwright (web) + - Paparazzi or Roborazzi ([Android](TODO)) + - XCUITest snapshots ([iOS](TODO)) + - Laravel Dusk (PHP) + - Any tool that produces PNG or JPEG files + + For a production reference, see Sentry's [`frontend-snapshots.yml`](https://github.com/getsentry/sentry/blob/master/.github/workflows/frontend-snapshots.yml) workflow. + +3. Modify an existing workflow or create a new workflow to upload snapshots on pushes to your main branch and on pull requests: + +```yml {filename:sentry_snapshots.yml} +name: Sentry Snapshots Upload + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + snapshots: + # Add your snapshot generation step here + # Then upload with `sentry-cli build snapshots` — see /product/snapshots/uploading-snapshots/ +``` + +Confirm that snapshots uploaded on `push` have the correct `head-sha` and no `base-sha` set, and that snapshots uploaded on `pull_request` have both `head-sha` and `base-sha` set. + +4. Confirm the status check appears + +After configuring the workflow, a **Snapshot Testing** status check should appear on every pull request. + +For details on the review and approval flow, see [Reviewing Snapshots](/product/snapshots/reviewing-snapshots/). + +## Troubleshooting + +### Status Check Not Appearing + +Check that: + +- The Sentry GitHub App is installed and has access to your repository. +- You're uploading snapshots from both your main branch (on `push`) and your pull request branches (on `pull_request`). +- The `--app-id` value matches between the head and base uploads. +- Your uploads include the correct git metadata (auto-detected in CI). + +### Missing Base Build + +The first time you set up Snapshots, your main branch may not have any uploads yet: + +1. Merge a PR or push to your main branch to trigger an upload. +2. Future PRs will be able to compare against this base build. + +### Wrong Base Snapshot Selected + +If diffs look unexpected, the wrong base may be selected. When checking out the PR commit, use the PR head SHA (not the merge commit) so Sentry resolves the correct base: + +```yml +- uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha || github.sha }} +``` diff --git a/docs/product/snapshots/reviewing-snapshots/index.mdx b/docs/product/snapshots/reviewing-snapshots/index.mdx index 94e7323523562..468c4794671bb 100644 --- a/docs/product/snapshots/reviewing-snapshots/index.mdx +++ b/docs/product/snapshots/reviewing-snapshots/index.mdx @@ -10,6 +10,8 @@ description: Review snapshot diffs on your pull request and approve changes. After you upload snapshots from a pull request branch, a **Snapshot Testing** GitHub Check appears on the pull request. If no snapshots changed, the check passes. If any snapshots were added, removed, or modified, the check fails and requires approval. +For setup instructions, see [Integrating Into CI](/product/snapshots/integrating-into-ci/). + IMAGE: GitHub Check showing Snapshot Testing results on a pull request ## Comparison Viewer diff --git a/docs/product/snapshots/uploading-snapshots/index.mdx b/docs/product/snapshots/uploading-snapshots/index.mdx index 0a431f3689789..025130439b874 100644 --- a/docs/product/snapshots/uploading-snapshots/index.mdx +++ b/docs/product/snapshots/uploading-snapshots/index.mdx @@ -6,6 +6,8 @@ description: Structure your snapshot directory and upload from CI with sentry-cl + + Snapshots works for any platform with a frontend. You can view specific platform examples [here](/product/snapshots#supported-platforms). This page covers the general upload structure and metadata schema. ## Upload command @@ -19,7 +21,7 @@ sentry-cli build snapshots \ --project \ ``` -You can reference our [example workflow](#upload-with-ci) and [full flag reference](#sentry-cli-build-snapshots-reference) below. +For an end-to-end CI setup, see [Integrating Into CI](/product/snapshots/integrating-into-ci/). The full flag reference is [below](#sentry-cli-build-snapshots-reference). ### Upload Structure @@ -64,64 +66,6 @@ Snapshots supports the following image formats: - PNG - JPEG -## Upload With CI - -For a production example, Sentry's Github action is available [here](https://github.com/getsentry/sentry/blob/master/.github/workflows/frontend-snapshots.yml). Below is an example GitHub Actions workflow you can use as a starting point. Replace the placeholder values with your own snapshot generation command, app ID, and Sentry project slug. - -```yml {filename:.github/workflows/snapshots.yml} -name: Snapshots - -on: - push: - branches: [main] - pull_request: - -env: - SNAPSHOT_OUTPUT_DIR: .artifacts/snapshots - -jobs: - snapshots: - runs-on: ubuntu-24.04 - timeout-minutes: 20 - steps: - - uses: actions/checkout@v4 - with: - # Use PR head SHA, not the merge commit — avoids phantom diffs - ref: ${{ github.event.pull_request.head.sha || github.sha }} - - # ------------------------------------------------------- - # YOUR SNAPSHOT GENERATION STEP(S) HERE - # ------------------------------------------------------- - # Generate PNG + JSON pairs into $SNAPSHOT_OUTPUT_DIR. - # Examples: - # - Playwright screenshots - # - iOS/Android screenshots - # - Laravel Dusk screenshots - # - Any tool that produces PNGs - # ------------------------------------------------------- - - name: Generate snapshots - run: - - - name: Install sentry-cli - if: ${{ !cancelled() }} - run: curl -sL https://sentry.io/get-cli/ | SENTRY_CLI_VERSION=3.3.4 sh - - - name: Upload snapshots - if: ${{ !cancelled() }} - env: - SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }} - run: | - ARGS=( - --auth-token "$SENTRY_AUTH_TOKEN" - build snapshots "${{ env.SNAPSHOT_OUTPUT_DIR }}" - --app-id - --project - ) - - - sentry-cli "${ARGS[@]}" -``` - ## `sentry-cli build snapshots` Reference ```bash diff --git a/includes/snapshots/ci-alert.mdx b/includes/snapshots/ci-alert.mdx new file mode 100644 index 0000000000000..4ad8297af2c1d --- /dev/null +++ b/includes/snapshots/ci-alert.mdx @@ -0,0 +1,5 @@ + + +Snapshots is most effective when part of your CI pipeline. To set up, follow our guide on [integrating into CI](/product/snapshots/integrating-into-ci/). + + diff --git a/includes/snapshots/github-only.mdx b/includes/snapshots/github-only.mdx new file mode 100644 index 0000000000000..dd6f517943ebb --- /dev/null +++ b/includes/snapshots/github-only.mdx @@ -0,0 +1 @@ +GitHub is currently the only supported integration for status checks.