How to Run ScreenshotMachine in a GitHub Actions Workflow

ScreenshotMachine’s official materials document a screenshot HTTP API with a bash example that uses curl; they do not document a separate ScreenshotMachine CLI executable. In GitHub Actions, run that API request from a shell step and store the returned image as a workflow file or artifact. The request needs your ScreenshotMachine customer key and the page URL. ScreenshotMachine’s API documentation shows the endpoint and request parameters.

1. Store the API key in GitHub Actions

In your repository, open Settings → Secrets and variables → Actions.
Create a repository secret named SCREENSHOTMACHINE_KEY and set it to your ScreenshotMachine customer key.
Reference the secret only in the step that makes the request. Do not put the key in checked-in YAML or print it in logs.

GitHub supports passing secrets to a step through its env mapping. See GitHub’s environment variable documentation.

2. Add a workflow that captures a page

Save this as .github/workflows/screenshot.yml. It can be started manually from the Actions tab. The request options shown are adapted from ScreenshotMachine’s documented bash example; this exact workflow has not been verified in a repository.

name: Capture website screenshot
on:
  workflow_dispatch:
jobs:
  screenshot:
    runs-on: ubuntu-latest
    steps:
      - name: Request screenshot
        env:
          SCREENSHOTMACHINE_KEY: ${{ secrets.SCREENSHOTMACHINE_KEY }}
        run: |
          curl -fGs "https://api.screenshotmachine.com" \
            --data-urlencode "key=$SCREENSHOTMACHINE_KEY" \
            --data-urlencode "url=https://example.com" \
            --data-urlencode "dimension=1366x768" \
            --data-urlencode "device=desktop" \
            --data-urlencode "format=png" \
            --data-urlencode "cacheLimit=0" \
            --data-urlencode "delay=2000" \
            --data-urlencode "zoom=100" \
            --output screenshot.png
      - name: Upload screenshot artifact
        uses: actions/upload-artifact@v4
        with:
          name: website-screenshot
          path: screenshot.png

The first step writes the response bytes to screenshot.png; -f makes curl return a failure status for HTTP errors, so the job fails instead of treating an HTTP error response as a successful capture. The second step makes the file downloadable from the completed workflow run. GitHub’s workflow syntax supports shell steps and workflow triggers; see the workflow syntax reference.

3. Set the page and capture options

The official example identifies key and url as required and shows these optional parameters:

Parameter	Purpose in the example	Example value
`dimension`	Requested image dimensions	`1366x768`
`device`	Device rendering preset	`desktop`
`format`	Image format	`png`
`cacheLimit`	Cache setting used by the sample	`0`
`delay`	Capture delay used by the sample	`2000`
`zoom`	Zoom setting used by the sample	`100`

For a full-page image, ScreenshotMachine’s sample uses a height of full, for example 1366xfull. Check the current API reference for accepted values before changing the dimensions or other option values.

4. Run the request locally with cURL

The same request can run in a terminal where SCREENSHOTMACHINE_KEY is set. This cURL form saves the response to a file and URL-encodes the target URL:

curl -fGs "https://api.screenshotmachine.com" \
  --data-urlencode "key=$SCREENSHOTMACHINE_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "dimension=1366x768" \
  --data-urlencode "device=desktop" \
  --data-urlencode "format=png" \
  --data-urlencode "cacheLimit=0" \
  --data-urlencode "delay=2000" \
  --data-urlencode "zoom=100" \
  --output screenshot.png

5. Call the API from Python or Node.js

Use a language script if the workflow needs to validate inputs, name files dynamically, or handle the image as part of other processing. These examples call the documented endpoint with the required key and URL. Install Python’s requests package in the job before running the Python version.

Python

import os
import requests

key = os.environ["SCREENSHOTMACHINE_KEY"]
response = requests.get(
    "https://api.screenshotmachine.com",
    params={
        "key": key,
        "url": "https://example.com",
        "dimension": "1366x768",
        "device": "desktop",
        "format": "png",
        "cacheLimit": "0",
        "delay": "2000",
        "zoom": "100",
    },
    timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
    image_file.write(response.content)

Node.js

const params = new URLSearchParams({
  key: process.env.SCREENSHOTMACHINE_KEY,
  url: 'https://example.com',
  dimension: '1366x768',
  device: 'desktop',
  format: 'png',
  cacheLimit: '0',
  delay: '2000',
  zoom: '100',
});

const response = await fetch(
  `https://api.screenshotmachine.com?${params}`
);
if (!response.ok) {
  throw new Error(`Screenshot request failed: HTTP ${response.status}`);
}
const image = Buffer.from(await response.arrayBuffer());
require('node:fs').writeFileSync('screenshot.png', image);

The direct curl step has the least setup for a single capture. A language script gives you more control over validation and file handling, but adds runtime code and, for Python, a dependency. The research does not verify a current ScreenshotMachine GitHub Action or SDK package version, so this guide uses the documented HTTP request.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One GET request can return a PNG, JPEG, WebP, or PDF. Its API accepts the parameter names used by other screenshot APIs, which can make switching simpler. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

Troubleshooting

Symptom	Likely cause	What to check
Key is empty or request is rejected	The repository secret is missing, misspelled, or unavailable to the workflow.	Confirm the secret is named `SCREENSHOTMACHINE_KEY` and is mapped under the request step’s `env`. Do not print its value while debugging.
The job fails with a curl error	Network failure, invalid request, or an HTTP error; `-f` causes curl to fail on HTTP error responses.	Read the curl exit status and GitHub step logs for non-secret context. Check endpoint, required parameters, account key, and target URL against the official API documentation.
Output file is missing	The request step failed before writing the image, or the upload step uses a different path.	Keep capture and upload paths identical. Ensure the upload runs only after the request succeeds.
The image shows an incomplete page	The page may need more time to render, or the requested dimensions do not fit the intended capture.	Review the documented `delay` and `dimension` options, and confirm accepted values in the API reference.
Workflow cannot access the secret on a pull request	GitHub restricts secrets in workflows triggered from forks.	Use a trusted trigger such as a manual run, or a protected workflow design. Do not expose the key to untrusted pull request code.

Performance, reliability, and cost considerations

Keep the request focused. Capture only when the workflow needs a new image. The documented sample includes cacheLimit; verify its current behavior and accepted values in the API reference before relying on caching.
Allow time for rendering. The API sample includes a delay option. Longer waits may increase job duration; choose a value appropriate to the target page and validate the resulting capture.
Fail visibly on HTTP errors. The curl -f flag causes a nonzero exit on HTTP errors, which prevents a failed response from silently passing the step. Use finite timeouts in custom scripts and handle exceptions explicitly.
Protect the credential. Scope the secret to the request step and avoid shell tracing or logging request parameters that contain the key.
Check account pricing and limits separately. The research sources do not establish current ScreenshotMachine pricing, quotas, or reliability figures, so this guide makes no such claims.

FAQ

Is there an official ScreenshotMachine CLI?

The official materials found for this guide document an HTTP API and a bash example using curl, not a distinct CLI executable.

Can I capture a full page?

The vendor sample shows a dimension such as 1366xfull. Confirm accepted values in the current API reference before using it.

Where do I get the downloaded image from a workflow?

The example uploads screenshot.png as an Actions artifact after the request step; download it from the completed workflow run.