To capture a webpage with Puppeteer in GitHub Actions, install the puppeteer package, let it download its compatible Chrome for Testing browser, save the screenshot to a known path, then upload that file with actions/upload-artifact. If your package manager blocks install scripts, run npx puppeteer browsers install explicitly after installing dependencies.
How to take a Puppeteer screenshot in GitHub Actions
This example uses Node.js 22 and npm. Treat the action and runtime versions as an illustrative pattern: pin versions to your project’s support policy and verify compatibility with your GitHub environment. GitHub’s artifact tutorial uses upload-artifact@v4, while the action repository has later release examples. GitHub’s artifact tutorial and the upload-artifact repository document the current options.
As an Amazon Associate I earn from qualifying purchases.
1. Add a screenshot script
Save this as screenshot.mjs in the repository root. It creates the output directory, opens the target page, writes a full-page PNG, and closes Chrome even if capture fails.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsimport { mkdir } from 'node:fs/promises';
import puppeteer from 'puppeteer';
await mkdir('artifacts', { recursive: true });
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.setViewport({ width: 1440, height: 900 });
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'artifacts/page.png', fullPage: true });
} finally {
await browser.close();
}Page.screenshot() writes to the filesystem when given a path; the Puppeteer guide also covers screenshots of individual elements. Puppeteer screenshot guide
#1 Best Overall
- SLIM. LIGHTWEIGHT. READY TO GO: The all-new slim design is perfect for busy lives on the go.
- SKILLFULLY DESIGNED. MILITARY TOUGH: Built with premium craftsmanship to withstand the occasional drop or ding.
- ALL-DAY, ALL-IN-ONE CHARGING: Power through your school day – and beyond – with a long-lasting 12-hour battery.¹
- 3X FASTER THAN THE PREVIOUS GENERATION OF WIFI: Crush your schoolwork in record time with Wi-Fi that’s three times faster than the previous generation of Wi-Fi.
- YOUR PHONE AND CHROMEBOOK WORK BETTER TOGETHER: Easily transfer files between devices, and control your phone right from your Chromebook.
2. Add the workflow
Save as .github/workflows/screenshot.yml. Commit the package manifest and lockfile so npm ci can install the project’s dependencies reproducibly.
name: screenshot
on: [workflow_dispatch]
jobs:
capture:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
- run: npm ci
# Keep this explicit if dependency install scripts are blocked.
- run: npx puppeteer browsers install
- run: node screenshot.mjs
- uses: actions/upload-artifact@v4
with:
name: page-screenshot
path: artifacts/page.png
if-no-files-found: errorThe explicit browser-install step is safe to keep when needed, but usually redundant: installing puppeteer normally downloads Chrome for Testing and chrome-headless-shell versions intended to work with that Puppeteer release. If install scripts are permitted and the browser download succeeded, you can omit the explicit step. Puppeteer installation guide
Install Chrome for Puppeteer in CI
Use Puppeteer-managed Chrome for the simplest setup
Install puppeteer rather than puppeteer-core when you want Puppeteer to download and manage its compatible browser. Puppeteer’s browser downloads are substantial: its installation documentation gives approximate Chrome for Testing download sizes of 170 MB on macOS, 282 MB on Linux, and 280 MB on Windows. Those estimates can change with browser versions. Puppeteer installation guide
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Run the browser installer if scripts are blocked
Some package-manager configurations block dependency lifecycle scripts, which can prevent Puppeteer’s normal browser download. Install dependencies, then run npx puppeteer browsers install. Alternatively, configure the package manager to allow Puppeteer’s install script. Use the explicit command when the workflow reports that Chrome is missing.
Rank #2
- FOR HOME, WORK, & SCHOOL – With an Intel processor, 14-inch display, custom-tuned stereo speakers, and long battery life, this Chromebook laptop lets you knock out any assignment or binge-watch your favorite shows..Voltage:5.0 volts
- HD DISPLAY, PORTABLE DESIGN – See every bit of detail on this micro-edge, anti-glare, 14-inch HD (1366 x 768) display (1); easily take this thin and lightweight laptop PC from room to room, on trips, or in a backpack.
- ALL-DAY PERFORMANCE – Reliably tackle all your assignments at once with the quad-core, Intel Celeron N4120—the perfect processor for performance, power consumption, and value (2).
- 4K READY – Smoothly stream 4K content and play your favorite next-gen games with Intel UHD Graphics 600 (3) (4).
- MEMORY AND STORAGE – Enjoy a boost to your system’s performance with 4 GB of RAM while saving more of your favorite memories with 64 GB of reliable flash-based eMMC storage (5).
Use an externally managed browser only when you need to
puppeteer-core does not download Chrome; it is intended for setups where the browser is managed separately. In that case, provide the executable path when launching Puppeteer and ensure the browser version is compatible with the Puppeteer version. Don’t switch to system Chrome just to fix a missing Puppeteer-managed download unless you specifically need external browser management.
Choose a readiness condition that fits the page
The sample waits for networkidle2, but a navigation wait is not a universal signal that a screenshot is ready. Pages with analytics, polling, streaming, or other continuing requests may not reach network idle reliably. If the page has a stable element that marks the content as ready, wait for that selector instead; for an application, use an appropriate app-specific readiness event. Adjust the wait condition to the page rather than adding a long arbitrary delay.
Save and download the screenshot artifact
The workflow uploads artifacts/page.png as an artifact named page-screenshot. After the run completes, open the workflow run in GitHub Actions and download the artifact from its summary. Artifacts preserve workflow files for later retrieval, including build outputs and debugging files. GitHub artifact tutorial
Choose the upload path and failure behavior
- Use the exact path your script writes. Create the parent directory before capturing, as the example does.
- Use
if-no-files-found: errorwhen a screenshot is a required output; without it, a missing file may only produce a warning. - Upload a single file for one screenshot, or a directory when the script creates several screenshots.
- In a matrix workflow, include the operating system or matrix dimension in each artifact name. Artifacts are immutable, so jobs cannot modify the same named artifact.
Set retention deliberately
The upload-artifact repository documentation says artifacts are retained for 90 days by default and describes retention-days values from 1 to 90. Repository, organization, or enterprise policy can impose a shorter limit, so check the policy for the repository rather than assuming a retention period. upload-artifact documentation
Rank #3
- Storage: 16GB Flash Memory
- OS: Chrome OS
- Screen Size: 11.6"
Troubleshoot common failures
“Could not find Chrome”
The package manager may have blocked Puppeteer’s install script. Run npx puppeteer browsers install after dependency installation, or allow Puppeteer’s postinstall script. Puppeteer installation guide
Chrome downloaded, but Puppeteer cannot find it
Puppeteer’s default browser cache has been ~/.cache/puppeteer since v19. Check that the install and runtime steps use compatible home and cache paths. To set a stable location explicitly, define PUPPETEER_CACHE_DIR for both installation and execution. Puppeteer configuration
Chrome exists but will not start on Linux
The runner may lack shared libraries or fonts required by the browser. Check Puppeteer’s Linux troubleshooting guidance for common Debian dependencies, and use ldd to identify unresolved shared libraries. The exact packages depend on the runner image. Avoid treating --no-sandbox as a blanket fix: it changes Chrome’s security posture and is not needed for the documented workflow. Puppeteer troubleshooting
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →The artifact is missing
Compare the screenshot’s output path with the upload action’s path, confirm the script created the parent directory, and check earlier workflow logs for capture errors. Set if-no-files-found: error to make a missing screenshot fail the job.
Rank #4
- Intel Celeron N4120: 4 Cores & Threads, 1.1GHz Base Clock, Up to 2.6GHz Boost Clock, 4MB Cache, Intel UHD Graphics 600. The perfect combination of performance, power consumption, and value helps your device handle multitasking smoothly and reliably with four processing cores to divide up the work.
Matrix jobs conflict over artifact names
Give each job a distinct artifact name, such as page-screenshot-ubuntu or a name that includes the matrix value. The action’s documentation explains that artifacts are immutable and multiple jobs cannot modify the same named artifact. upload-artifact documentation
Or skip the browser setup
ScreenshotNeo offers a one-request screenshot API if you don’t want to install or maintain a browser in the workflow. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. It also has an MCP server that lets AI agents take screenshots. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo.
For example, store your API key as a GitHub Actions secret and pass it as an environment variable:
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key="$SCREENSHOTNEO_API_KEY"
--data-urlencode url=https://example.com
-o shot.webpSee the ScreenshotNeo API documentation for options. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can I capture a specific element instead of the full page?
Yes. Puppeteer’s screenshot guide documents element screenshots as well as page screenshots; use the element screenshot method for the target element.
Can the workflow run on every push instead of manually?
Yes. Replace the illustrative workflow_dispatch trigger with the events appropriate to your repository, such as a push or pull request trigger.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
