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.
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
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
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 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
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).
Every call answers 200 with a PNG.
Six pictures, named home-1280.png to blog-390.png. Summary: 6 taken, 0 failed.
The second call answers 429 with Retry-After: 1.
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.
Waited 2 seconds, then 4, then the third try passed.
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.
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.
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.
Every call answers 422 invalid_options.
One call per picture and no retry, because a wrong request fails the same way each time.
Nothing listens on the API address.
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.
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.
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 run | Pictures a month | Smallest plan |
|---|---|---|---|
| 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 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]GitHub Docs, Events that trigger workflows: workflows in forked repositories. Checked .
- [2]GitHub, actions/upload-artifact README. Checked .
- [3]GitHub Docs, Control the concurrency of workflows and jobs. Checked .
- [4]GitHub Docs, Workflow syntax: the default shell on Linux is bash -e {0}. Checked .
Read next
- GuideVisual regression testing, explained in picturesHow 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.
- GuideHow to screenshot a page behind a login, safelyFour 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.
- PlaybookHow to screenshot a list of URLs in bulkScreenshot hundreds or thousands of URLs: a queue simulator that says how long it takes, a short Node.js script, and what fails at scale.