Skip to content
CI workflowBy 7 min read

Screenshot every pull request in GitHub Actions

Pick the pages and the widths. The file on the right is a workflow you can paste, and the box above it says how many screenshots a month it will use.

Build the file

One path per line, starting with a slash. Up to 20.

Widths
Options

3 pages × 2 widths = 6 pictures a run

180 a month

30 runs a month. The smallest plan that holds it is Starter (3,000 a month).

  • Free100
  • Starter3,000
  • Growth15,000
  • Scale60,000
.github/workflows/preview-shots.yml
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

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.

Set it up in four steps

    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.

    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.

    Add the file

    Save the YAML as .github/workflows/preview-shots.yml and push it on a branch.

    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.

The key stays in a secret

Never paste the access key into the file. A pull request can change the file, and a workflow run prints its commands in the log. The file reads the key from secrets.SHOT_API_KEY, and GitHub hides a secret in the log.

What it does with each answer

A CI step that retries everything wastes minutes, and one that retries nothing fails on a busy minute. Five rules sit between them. The status codes come from the errors page of the docs, and the default shell of a run step is bash -e [4].

The answerWhat the script doesWhy
200 and Content-Type image/*Keep the file, go onThe two checks the docs give for success.
200 with another content typeFail the picture, no retryNot a picture, and asking again will not change that.
429, 500, 502, 503, 504, or 000 (no answer)Retry, up to 3 triesThese depend on the moment. A 429 waits for Retry-After, otherwise 2 s, then 4 s.
401, 402, 403Stop the whole stepThe 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 restFail the picture, no retryThe request is wrong. Fix the page list or the options.

What it did in the test

Ten runs on 11 November 2026, each against a stand-in server that played one situation. Six pictures were asked for in each (3 pages at 2 widths).

Step passed6 calls · 6 kept · 0.3 s

Every call answers 200 with a PNG.

Six pictures, named home-1280.png to blog-390.png. Summary: 6 taken, 0 failed.

Step passed7 calls · 6 kept · 1.3 s

The second call answers 429 with Retry-After: 1.

Waited the 1 second the header named, sent the same call again, and it passed.

Step passed8 calls · 6 kept · 6.5 s

The first two calls answer 429 with no Retry-After.

Waited 2 seconds, then 4, then the third try passed.

Step failed10 calls · 4 kept · 13.4 s

Every call for /pricing answers 503.

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.

Step failed3 calls · 2 kept · 0.2 s

From the third call on: 402 quota_exceeded.

Stopped on the first 402 without trying again: every later call would fail the same way. Summary: Stopped by HTTP 402 after 2 pictures.

Step failed6 calls · 0 kept · 0.4 s

Status 200, but the body is JSON, not a picture.

Did not trust the status alone. It checks the Content-Type, saw JSON, kept nothing and did not retry.

Step failed6 calls · 0 kept · 0.4 s

Every call answers 422 invalid_options.

One call per picture and no retry, because a wrong request fails the same way each time.

Step failed0 calls · 0 kept · 37 s

Nothing listens on the API address.

curl reports status 000. Three tries for each picture, with waits of 2 and 4 seconds, then failed.

Step passed6 calls · 6 kept · 0.3 s

The preview answers 503 three times, then 200.

Four requests to the preview and three waits of 10 seconds (counted, not waited), and only then the six calls to the API.

Step passed6 calls · 6 kept · 0.2 s

The same preview, with the wait step switched off in the builder.

No request to the preview at all. The six calls went out at once.

Besides these runs, the file was built for 288 combinations of pages, widths, options and format. Each was read as YAML, had a step list of the right shape, and its script passed bash -n. Every option name in the requests was found on the docs' options page. 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.

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.[2]

What it costs

One successful render is one screenshot of your plan. Failed calls and cache hits are free. A new push cancels the run still going on the same pull request [3], and the pictures that run already took still count.

Setup (2 widths)Pictures a runPictures a monthSmallest plan
3 pages, 10 pull requests, 3 pushes each6180Starter
5 pages, 30 pull requests, 4 pushes each101,200Starter
8 pages, 60 pull requests, 5 pushes each164,800Growth
12 pages, 150 pull requests, 6 pushes each2421,600Scale

The Free plan has 100 screenshots a month and needs no card, which is 16 runs of the default setup. Starter has 3,000, Growth 15,000 and Scale 60,000. See the plans.

Where it still fails

  • Pull requests from forks get no secrets, so the job is skipped for them [1]. GitHub treats Dependabot pull requests the same way, so they are skipped too.
  • The pictures are saved, not compared. To see what changed between two runs, add a diff step; the visual regression guide lists the tools.
  • The cache option is left off on purpose: a stored copy of a page that changed in the last push is a stale picture.
  • A preview behind a login needs a cookie or a header on the request. See screenshots behind a login.
  • Artifacts are kept for the retention period of the repository, up to 90 days unless the settings change it [2]. For a longer record, copy the files elsewhere.

Questions people ask

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. [1]GitHub Docs, Events that trigger workflows: workflows in forked repositories. Checked .
  2. [2]GitHub, actions/upload-artifact README. Checked .
  3. [3]GitHub Docs, Control the concurrency of workflows and jobs. Checked .
  4. [4]GitHub Docs, Workflow syntax: the default shell on Linux is bash -e {0}. Checked .

Screenshot any page in one step

Paste an address into CurlShot and download the screenshot. A free account gives you 100 screenshots every month. No card needed.