feat: accept or reject screenshot diffs from a browser page

.github/actions/accept-screenshots/action.yml

@@ -0,0 +1,34 @@
+---
+name: 'Accept SnapDiff screenshots'
+description: >-
+  Commit screenshot baselines accepted in a PR comment or a new issue
+  (`/snap-diff accept run=<run id> [pr=<n>] <file>@<hash> ...`) from that run's report artifact.
+  Run it from an issue_comment + issues workflow gated to OWNER/MEMBER/COLLABORATOR.
+inputs:
+  token:
+    description: 'Token with contents: write, pull-requests: write, issues: write, actions: read (actions: write to dispatch ci-workflow); reads the author''s permission'
+    default: ${{ github.token }}
+  screenshots-path:
+    description: 'Every accepted file must be committed under this directory (relative to the repository root)'
+    default: 'doc/screenshots'
+  ci-workflow:
+    description: >-
+      Optional workflow file name (with workflow_dispatch) to run on the PR branch after the commit.
+      A push made with GITHUB_TOKEN does not start workflows; a workflow_dispatch does.
+    default: ''
+runs:
+  using: 'composite'
+  steps:
+    - name: Accept screenshots
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        CI_WORKFLOW: ${{ inputs.ci-workflow }}
+        SCREENSHOTS_PATH: ${{ inputs.screenshots-path }}
+        EVENT_NAME: ${{ github.event_name }}
+        ISSUE_NUMBER: ${{ github.event.issue.number }}
+        # issue_comment: the comment on the PR; issues: the new issue itself.
+        BODY: ${{ github.event_name == 'issues' && github.event.issue.body || github.event.comment.body }}
+        AUTHOR: ${{ github.event_name == 'issues' && github.event.issue.user.login || github.event.comment.user.login }}
+        AUTHOR_ASSOCIATION: ${{ github.event_name == 'issues' && github.event.issue.author_association || github.event.comment.author_association }}
+      run: ruby "$GITHUB_ACTION_PATH/accept_screenshots.rb"

.github/actions/upload-screenshots/action.yml

@@ -77,6 +77,9 @@ runs:
     - name: Job summary
       if: steps.check-report.outputs.exists == 'true'
       shell: bash
+      env:
+        HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+        REPO: ${{ github.repository }}
       run: |
         cat >> "$GITHUB_STEP_SUMMARY" <<EOF
         ### SnapDiff Report
@@ -86,6 +89,9 @@ runs:
         | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
         | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
         EOF
+        if [ "$HEAD_REPO" = "$REPO" ]; then
+          printf '\nTo accept: open the HTML report, mark Accept/Reject, then Commit decisions.\n' >> "$GITHUB_STEP_SUMMARY"
+        fi
 
     - name: Find existing PR comment
       if: inputs.pr-comment == 'true' && github.event_name == 'pull_request'
@@ -111,3 +117,5 @@ runs:
           | HTML report (inline) | ${{ steps.upload-report.outputs.artifact-url || 'N/A' }} |
           | Full report with images | ${{ steps.upload-report-full.outputs.artifact-url || 'N/A' }} |
           | [All artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) | Browse all |
+
+          ${{ steps.check-report.outputs.exists == 'true' && github.event.pull_request.head.repo.full_name == github.repository && 'To accept: open the HTML report, mark Accept/Reject, then Commit decisions.' || '' }}

.github/workflows/snap-diff-accept.yml

@@ -0,0 +1,46 @@
+---
+name: Accept screenshots
+
+# The report's "Commit decisions" button opens a new issue whose body is the
+# review command (or a maintainer pastes it as a PR comment):
+#   /snap-diff accept run=<run id> [pr=<n>] <file>@<hash> ...
+# The action commits those files from that run's report artifact to the PR branch.
+
+on:
+  issue_comment:
+    types: [ created ]
+  issues:
+    types: [ opened ]
+
+jobs:
+  accept:
+    if: >-
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request &&
+       startsWith(github.event.comment.body, '/snap-diff ') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'issues' &&
+       startsWith(github.event.issue.body, '/snap-diff ') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association))
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      actions: write
+    # Per PR for comments, per issue for issues (the PR is not known yet);
+    # two issues for one PR may run at once, and the push lease lets only one land.
+    concurrency:
+      group: snap-diff-accept-${{ github.event.issue.number }}
+      cancel-in-progress: false
+    steps:
+      # The default branch (the ref of both events): this repository's trusted
+      # code, needed for the local action. The PR's code is never checked out here.
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/accept-screenshots
+        with:
+          screenshots-path: test/fixtures/app/doc/screenshots
+          ci-workflow: test.yml

.github/workflows/test.yml

@@ -95,6 +95,8 @@ jobs:
         if: failure()
         with:
           name: base-screenshots
+          # The suite writes its report under its own SnapDiff root.
+          report-path: test/fixtures/app/doc/screenshots
           pr-comment: 'true'
 
       - name: Uploading Coverage Report

.gitignore

@@ -20,6 +20,7 @@
 *.diff.png
 *.base.png
 snap_diff_report.html
+snap_diff_manifest.json
 
 *.attempt_*.webp
 *.diff.webp

CHANGELOG.md

@@ -20,6 +20,13 @@ kept as history. This entry is the one to read if you are coming from **1.15.1**
 
 ### Added
 
+- **Accept screenshots from the CI report.** On GitHub Actions, the HTML report gets Accept/Reject
+  buttons and a "Commit decisions" button that opens a prefilled GitHub issue. Submitting it (or pasting
+  the copied command as a PR comment) runs the new `accept-screenshots` action, which commits the exact
+  CI pixels to the PR branch with the repository's `GITHUB_TOKEN`. The report also writes `snap_diff_manifest.json`, and
+  `upload-screenshots` adds a how-to-accept line to its PR comment and job summary. See
+  [CI integration](docs/ci-integration.md#accept-screenshots-from-the-pull-request).
+
 - **`SNAP_DIFF_ACCEPT_SCREENSHOTS=1` re-records changed baselines for one run.** The variable
   selects `record = :all` for the run that sees it, outranking `record =` and `fail_if_new`; a
   `record:` on the screenshot still outranks it. `1` and `true` turn it on; any other value is the

README.md

@@ -115,6 +115,7 @@ Add diff artifacts to `.gitignore` — these are generated at runtime and should
 *.diff.webp
 *.base.webp
 snap_diff_report.html
+snap_diff_manifest.json
 ```
 
 If you skip Step 2 and push to CI, the build will fail — `fail_if_new` is `true` by default in CI.
@@ -232,7 +233,7 @@ After tests run, open `doc/screenshots/snap_diff_report.html`:
 
 ![SnapDiff Web UI — annotated diff showing changed regions highlighted in red](docs/images/snap_diff_annotated.png)
 
-See [Web UI & Custom Reporters](docs/reporters.md) for full feature details and [CI Integration](docs/ci-integration.md) for GitHub Actions setup.
+See [Web UI & Custom Reporters](docs/reporters.md) for full feature details and [CI Integration](docs/ci-integration.md) for GitHub Actions setup, including [accepting screenshots from a PR comment](docs/ci-integration.md#accept-screenshots-from-the-pull-request).
 
 ## AI-Assisted Triage (optional)
 

Rakefile

@@ -69,7 +69,7 @@ desc "Remove screenshot diff artifacts (keeps baselines)"
 task "snap_diff:clean" do
   patterns = ["**/*.diff.png", "**/*.base.png", "**/*.base.diff.png", "**/*.heatmap.diff.png",
     "**/*.diff.webp", "**/*.base.webp", "**/*.base.diff.webp", "**/*.heatmap.diff.webp",
-    "**/snap_diff_report.html"]
+    "**/snap_diff_report.html", "**/snap_diff_manifest.json"]
   removed = patterns.flat_map { |p| Dir.glob("tmp/#{p}") + Dir.glob("doc/screenshots/#{p}") }.uniq
   removed.each { |f| FileUtils.rm_f(f) }
   puts "Removed #{removed.size} diff artifacts"

docs/ci-integration.md

@@ -283,4 +283,81 @@ Two things this minimal recipe does not do:
 2. Enter the branch name (e.g. your PR branch)
 3. The workflow records new and changed baselines, commits, and pushes
 
+## Accept screenshots from the pull request
+
+When a CI run fails on screenshot diffs, a reviewer can accept the new pixels without checking out the
+branch. In the HTML report (the inline link in the PR comment), each changed or new screenshot has
+Accept and Reject buttons (keys `Y` and `N`). "Commit decisions" opens a new GitHub issue already
+filled in with a command like `/snap-diff accept run=123 pr=45 linux/cuprite/index.png@0123456789abcdef`.
+Click Submit. A workflow commits those exact files from that run's report artifact to the PR branch
+with the repository's own `GITHUB_TOKEN`, posts the result on the PR, closes the issue and re-runs CI.
+The buttons appear only in reports built on GitHub Actions.
+
+If the link would be too long for GitHub, the button is disabled. Use "Copy review command" and paste
+the command as a comment on the pull request instead; it does the same thing.
+
+To install it, copy this workflow. Set `screenshots-path` to your `save_path`. `ci-workflow` is
+optional: it names your test workflow, which needs an `on: workflow_dispatch` trigger. Without it the
+reply asks you to re-run CI by hand, because a push made with `GITHUB_TOKEN` does not start workflows.
+
+```yaml
+# .github/workflows/snap-diff-accept.yml
+name: Accept screenshots
+
+on:
+  issue_comment:
+    types: [created]
+  issues:
+    types: [opened]
+
+jobs:
+  accept:
+    if: >-
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request &&
+       startsWith(github.event.comment.body, '/snap-diff ') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'issues' &&
+       startsWith(github.event.issue.body, '/snap-diff ') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association))
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      actions: write   # read is enough if you leave out ci-workflow
+    concurrency:
+      group: snap-diff-accept-${{ github.event.issue.number }}
+      cancel-in-progress: false
+    steps:
+      - uses: snap-diff/snap_diff-capybara/.github/actions/accept-screenshots@master
+        with:
+          screenshots-path: doc/screenshots
+          ci-workflow: test.yml
+```
+
+`issue_comment` and `issues` workflows run only from the default branch, so merge this file first.
+Until then the issue or comment does nothing.
+
+Reviewers need write access to the repository. The workflow checks the permission API as well as the
+`author_association`, so read-only collaborators are refused, and their issue is closed with the reason.
+
+Limits:
+
+- Pull requests from the same repository only. A fork PR is refused.
+- Git LFS paths are refused. Accept those locally.
+- Screenshot paths may use only `A-Z a-z 0-9 . _ - /` (no spaces) and must sit under `screenshots-path`.
+- The report artifact must still exist. `upload-screenshots` keeps it `retention-days` days (default 2).
+- Only the PR's current head can be accepted. After a new push, review the new run's report.
+- Only the last capture of a file can be accepted. Earlier captures of it show a note instead of the buttons.
+
+Security: the workflow never checks out or runs the PR's code. It downloads the report artifact, takes
+the paths from the report's manifest, and commits a file only if its SHA-256 matches the hash in the
+reviewer's command and its bytes are a PNG or WebP. It pushes only to the PR branch, and only while
+that branch is still at the commit the run tested. The design does rely on trust you already extend:
+whoever opens a same-repository PR can already push to the repository, and their CI run produces the
+artifact. Beyond that, the permission check and your branch protection limit the damage. Do not enable
+this for forks, and do not give the bot a ruleset bypass: with branch protection in place, a push the
+rules reject fails instead of landing.
+
 [← Back to README](../README.md)

docs/organization.md

@@ -33,7 +33,7 @@ version control system (git).
 
 Screenshots are compared to the previously COMMITTED version of the same screenshot.
 
-**Note:** When a screenshot differs, diff artifacts (`.diff.png`, `.heatmap.diff.png`, etc.) are generated alongside the baseline. Add `*.diff.png`, `*.base.png`, `*.diff.webp`, `*.base.webp`, and `snap_diff_report.html` to your `.gitignore`. Clean up artifacts with `rake snap_diff:clean`.
+**Note:** When a screenshot differs, diff artifacts (`.diff.png`, `.heatmap.diff.png`, etc.) are generated alongside the baseline. Add `*.diff.png`, `*.base.png`, `*.diff.webp`, `*.base.webp`, `snap_diff_report.html`, and `snap_diff_manifest.json` to your `.gitignore`. Clean up artifacts with `rake snap_diff:clean`.
 
 ## Screenshot groups
 

docs/reporters.md

@@ -24,6 +24,10 @@ committing it is what accepts it). Their count in the report is the summary line
 
 **Note:** The report is not written when every screenshot matched and none is new.
 
+It also writes `snap_diff_manifest.json`, one entry per changed or new screenshot. The
+[accept workflow](ci-integration.md#accept-screenshots-from-the-pull-request) reads it to find where
+each accepted file goes. Add it to your `.gitignore` next to `snap_diff_report.html`.
+
 ## The end-of-run summary
 
 Every run ends with what it actually did, whether or not you require a reporter: