# Screenshot every pull request in GitHub Actions

> Build a GitHub Actions workflow that screenshots your pull request preview on every push: pages, widths and format, retries, and a plan size.

CI workflow by Serghei Pogor, founder of CurlShot (https://curlshot.com/about/serghei-pogor). Published 11 November 2026. Page for people: https://curlshot.com/blog/screenshot-pull-requests-github-actions

Add a workflow that runs on pull_request, waits for the preview, calls the CurlShot screenshot endpoint once per page and width with the key in a secret, retries 429 and 5xx answers up to three times, and uploads the pictures as an artifact. The default setup of three pages at two widths takes six pictures a run. At ten pull requests with three pushes each, that is 180 a month, which is more than the 100 of the Free plan.

## Key facts

- The default workflow takes 6 pictures a run (3 pages at 2 widths). The Free plan of CurlShot holds 16 such runs a month.
- Only some errors are worth a retry. A 429 or a 5xx answer, or no answer at all, can pass on a second try. A 401, 402 or 403 will fail every later picture, so the script stops at once.
- A 200 status is not enough: the script also checks that the Content-Type is an image, so a JSON body is never saved as a picture.
- Secrets are not passed to pull requests from forks, and GitHub treats Dependabot pull requests the same way. The workflow skips both.
- A new push cancels the run still going on the same pull request, but pictures already taken still count toward the plan.

## The workflow

The file the builder on the page produces with its default settings (3 pages, a desktop and a phone width, full page, cookie banners hidden, wait for the preview). The page lets you change the pages, the widths and the format.

```yaml
name: Preview screenshots
on:
  pull_request:
    types: [opened, synchronize, reopened]
permissions:
  contents: read
concurrency:
  group: preview-shots-${{ github.event.pull_request.number }}
  cancel-in-progress: true
jobs:
  shots:
    # Secrets are not passed to pull requests from forks or from Dependabot
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      SHOT_API: https://curlshot.com/api/v1/screenshot
      SHOT_KEY: ${{ secrets.SHOT_API_KEY }}
      PREVIEW_URL: ${{ vars.PREVIEW_URL }}
      PR: ${{ github.event.pull_request.number }}
    steps:
      - name: Take the pictures
        run: |
          set -uo pipefail
          base="${PREVIEW_URL//\{pr\}/$PR}"
          base="${base%/}"
          mkdir -p shots
          ok=0; failed=0

          # Wait for the preview to answer, up to 5 minutes
          for try in $(seq 1 30); do
            code=$(curl -s -o /dev/null -w '%{http_code}' "$base/")
            if [ "$code" -ge 200 ] && [ "$code" -lt 400 ]; then break; fi
            if [ "$try" = 30 ]; then echo "::warning::The preview did not answer in 5 minutes"; else sleep 10; fi
          done

          # shoot PATH WIDTH FILE: up to 3 tries, and only for errors that can pass
          shoot() {
            local attempt status ctype pause
            for attempt in 1 2 3; do
              status=$(curl -sG "$SHOT_API" -H "X-Access-Key: $SHOT_KEY" \
                --data-urlencode "url=$base$1" -d "viewport_width=$2" -d format=png -d full_page=true -d block_cookie_banners=true \
                -o "$3" -D headers.txt -w '%{http_code}')
              ctype=$(grep -i '^content-type:' headers.txt | tr -d '\r' | tr 'A-Z' 'a-z')
              if [ "$status" = 200 ] && [[ "$ctype" == *image/* ]]; then return 0; fi
              case "$status" in
                401|402|403)
                  echo "::error::HTTP $status: $(head -c 200 "$3" 2>/dev/null)"
                  rm -f "$3"
                  echo "Stopped by HTTP $status after $ok pictures" >> "$GITHUB_STEP_SUMMARY"
                  exit 1 ;;
                000|429|500|502|503|504) ;;
                *) break ;;
              esac
              [ "$attempt" = 3 ] && break
              pause=$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')
              sleep "${pause:-$((attempt * 2))}"
            done
            echo "::error::$1 at $2 px: HTTP $status $(head -c 200 "$3" 2>/dev/null)"
            rm -f "$3"
            return 1
          }

          while IFS= read -r page; do
            [ -z "$page" ] && continue
            name=$(printf '%s' "$page" | tr -c 'A-Za-z0-9' '-' | sed 's/^-*//; s/-*$//')
            name=${name:-home}
            for width in 1280 390; do
              if shoot "$page" "$width" "shots/$name-$width.png"; then ok=$((ok + 1)); else failed=$((failed + 1)); fi
            done
          done <<'PAGES'
          /
          /pricing
          /blog
          PAGES

          echo "$ok pictures taken, $failed failed" >> "$GITHUB_STEP_SUMMARY"
          [ "$failed" = 0 ]
      - name: Keep the pictures
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: preview-shots-pr-${{ github.event.pull_request.number }}
          path: shots/
          if-no-files-found: ignore
```

## Set it up

1. **Save the key as a secret.** In the repository settings, add an Actions secret called SHOT_API_KEY with your access key. It is read only in the workflow, and never typed into the file.
2. **Save the preview address as a variable.** Add an Actions variable called PREVIEW_URL, with {pr} where the pull request number goes, for example https://pr-{pr}.example.dev, and no slash at the end.
3. **Add the file.** Save the YAML as .github/workflows/preview-shots.yml and push it on a branch.
4. **Open a pull request.** The run starts on its own. The pictures are in the run page, under Artifacts, and the step summary says how many were taken.

## What the script does with each answer

| The answer | What the script does | Why |
| --- | --- | --- |
| 200 and Content-Type image/* | Keep the file, go on | The two checks the docs give for success. |
| 200 with another content type | Fail the picture, no retry | Not a picture, and asking again will not change that. |
| 429, 500, 502, 503, 504, or 000 (no answer) | Retry, up to 3 tries | These depend on the moment. A 429 waits for Retry-After, otherwise 2 s, then 4 s. |
| 401, 402, 403 | Stop the whole step | The key, the quota or the plan is the problem, and every later picture would fail the same way. Failed calls are free. |
| 400, 404, 413, 422 and the rest | Fail the picture, no retry | The request is wrong. Fix the page list or the options. |

## What it did in the test

| The stand-in server | Step | API calls | Pictures kept | Seconds | What the script did |
| --- | --- | --- | --- | --- | --- |
| Every call answers 200 with a PNG. | passed | 6 | 6 | 0.3 | Six pictures, named home-1280.png to blog-390.png. Summary: 6 taken, 0 failed. |
| The second call answers 429 with Retry-After: 1. | passed | 7 | 6 | 1.3 | Waited the 1 second the header named, sent the same call again, and it passed. |
| The first two calls answer 429 with no Retry-After. | passed | 8 | 6 | 6.5 | Waited 2 seconds, then 4, then the third try passed. |
| Every call for /pricing answers 503. | failed | 10 | 4 | 13.4 | Three tries for each of the two /pricing pictures, then gave up on them. The four other pictures were kept, the step failed, the summary says 4 taken, 2 failed. |
| From the third call on: 402 quota_exceeded. | failed | 3 | 2 | 0.2 | Stopped on the first 402 without trying again: every later call would fail the same way. Summary: Stopped by HTTP 402 after 2 pictures. |
| Status 200, but the body is JSON, not a picture. | failed | 6 | 0 | 0.4 | Did not trust the status alone. It checks the Content-Type, saw JSON, kept nothing and did not retry. |
| Every call answers 422 invalid_options. | failed | 6 | 0 | 0.4 | One call per picture and no retry, because a wrong request fails the same way each time. |
| Nothing listens on the API address. | failed | 0 | 0 | 37 | curl reports status 000. Three tries for each picture, with waits of 2 and 4 seconds, then failed. |
| The preview answers 503 three times, then 200. | passed | 6 | 6 | 0.3 | Four requests to the preview and three waits of 10 seconds (counted, not waited), and only then the six calls to the API. |
| The same preview, with the wait step switched off in the builder. | passed | 6 | 6 | 0.2 | No request to the preview at all. The six calls went out at once. |

## What the first draft got wrong

- **A 402 left a JSON file named like a picture.** In the quota case the script stopped, but the error text was already saved as shots/pricing-1280.png, and the upload step would have kept it as a picture. The script now deletes the file before it stops, and writes a line to the summary.
- **A refused connection was not retried.** With nothing listening, curl gives status 000, which fell into the "do not retry" branch. A network blip would have failed the job at once. 000 now counts with 429 and the 5xx codes. The same case printed three "cannot open file" lines from head, which is silenced.
- **The upload action version.** The draft used actions/upload-artifact@v4. On 11 November 2026 the README of that action shows @v7 in its example, so the workflow uses @v7. This one was not run on GitHub.

## What it costs

A run takes one picture for every page at every width. One successful render counts as one screenshot of your plan, and a cancelled run still counts what it already took.

| Setup | Pictures a run | Pictures a month | Smallest plan that holds it |
| --- | --- | --- | --- |
| 3 pages, 10 pull requests, 3 pushes each | 6 | 180 | Starter |
| 5 pages, 30 pull requests, 4 pushes each | 10 | 1,200 | Starter |
| 8 pages, 60 pull requests, 5 pushes each | 16 | 4,800 | Growth |
| 12 pages, 150 pull requests, 6 pushes each | 24 | 21,600 | Scale |

The Free plan has 100 screenshots a month, which is 16 runs of the default setup. Plans: Free 100, Starter 3,000, Growth 15,000, Scale 60,000 a month. See [pricing](https://curlshot.com/pricing).

## Where it still fails

- Pull requests from forks get no secrets, so the job is skipped for them. GitHub treats Dependabot pull requests the same way, so the job is skipped for them too.
- The pictures are saved, not compared. Pair them with a diff tool, see [the visual regression guide](https://curlshot.com/blog/visual-regression-testing-guide).
- The cache option is left off on purpose: a stored copy of a page you just changed would defeat the point.
- A preview behind a login needs a cookie or header, see [screenshots behind a login](https://curlshot.com/blog/screenshot-pages-behind-login).
- Artifacts are kept for the retention period of the repository.

## How it was tested

The "Take the pictures" script of the generated workflow was run ten times on the lab host, each time against a small stand-in server that answered the way the errors page of the docs describes. Every picture was a one-pixel PNG. The preview was a second path on the same stand-in server. In the preview test, sleep was replaced by a program that only writes its argument to a file, so the three ten-second waits were counted and not waited. The request itself was not sent to the real API in this run (no access key on the lab host), and the workflow was not run on GitHub. What is shown was run: the generated file read as YAML, its script checked with bash -n, and the script run against a stand-in server. Tested on 11 November 2026.

## Questions

### How do I take a screenshot of a pull request preview in GitHub Actions?

Run a workflow on pull_request, build the preview address from the pull request number, and send one request per page to the CurlShot screenshot endpoint with curl. Save each answer as a file and upload the folder with actions/upload-artifact. The builder on this page writes the whole file.

### Why does the workflow skip pull requests from forks?

With the exception of the GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository, so the access key would be empty and every call would fail with a 401. GitHub docs read on 2026-11-11 say Dependabot pull requests are treated the same way.

### Which errors should a CI screenshot step retry?

Retry 429 after the Retry-After wait, retry 500, 502, 503 and 504 with a short pause, and retry a call that got no answer. Do not retry 400, 422 or 413, because the request is wrong, and stop the whole step on 401, 402 and 403.

### How many screenshots will a pull request workflow use?

Pages times widths, times pushes, times pull requests. Three pages at two widths with 10 pull requests of 3 pushes each is 180 a month. One successful render is one screenshot of your plan, and the Free plan of CurlShot has 100 a month without a card.

### Should the screenshot call use the cache?

Not in this workflow. A stored copy of a preview that changed in the last push is a stale picture. Leave the cache option off so each run takes a new one.

## Sources

1. GitHub Docs, "Events that trigger workflows: workflows in forked repositories": https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows (checked 11 November 2026)
2. GitHub, "actions/upload-artifact README": https://github.com/actions/upload-artifact (checked 11 November 2026)
3. GitHub Docs, "Control the concurrency of workflows and jobs": https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency (checked 11 November 2026)
4. GitHub Docs, "Workflow syntax: the default shell on Linux is bash -e {0}": https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax (checked 11 November 2026)

## Go deeper

- [Screenshot API](https://curlshot.com/tools/screenshot-api)
- [Errors and retries](https://curlshot.com/docs/errors)
- [Usage and limits](https://curlshot.com/docs/usage-and-limits)
- [Pricing](https://curlshot.com/pricing)

## Read next

- [Visual regression testing, explained in pictures](https://curlshot.com/blog/visual-regression-testing-guide.md): How screenshot comparison works, why visual tests go flaky and how to fix each cause, the tools, and a set-up checklist with a Playwright example.
- [How to screenshot a page behind a login, safely](https://curlshot.com/blog/screenshot-pages-behind-login.md): Four ways to screenshot a page that needs a login: session cookie, bearer token, Basic auth or a signed link. What each one risks, and the safest pattern.
- [How to screenshot a list of URLs in bulk](https://curlshot.com/blog/bulk-screenshots-list-of-urls.md): Screenshot hundreds or thousands of URLs: a queue simulator that says how long it takes, a short Node.js script, and what fails at scale.
