Guides · 2026-10-20

Catch mobile layout bugs on every Vercel and Netlify preview (GitHub workflow)

Most layout bugs that reach production were visible on the preview deploy. Nobody opened it on a phone. Reviewers read the diff, maybe click the desktop preview link, and approve. The table that scrolls sideways at 393 px, or the script that throws on Safari-sized screens, ships.

This guide adds one GitHub workflow that renders every preview deploy on phone, tablet and desktop, checks each one for the problems people actually notice, and posts the result on the pull request. It works with Vercel, Netlify and anything else that reports GitHub deployment statuses.

What gets checked

Each page is loaded in real Chromium at each device size. Next to the screenshot you get:

• Sideways scrolling, with the elements that cause it (for example table.pricing (580px wide, ends at 596px)), so the fix is obvious.
• A missing viewport tag. Without <meta name="viewport">, phones lay the page out 980 px wide and shrink it. The homepage of berkshirehathaway.com is a real example: on an iPhone it reports "phones lay the page out 980px wide and shrink it to fit the 393px screen, so text is tiny".
• Uncaught JavaScript errors and console errors. A page can return clean HTML and still render half-empty because a script threw.
• Failed requests: 4xx/5xx responses and network errors for scripts, styles, images and API calls. Small things show up too: craigslist.org's sites page currently requests a favicon that answers 404.
• Broken images that never loaded.

Under the hood this is one API call, /v1/check:

curl "https://shotlane.dev/v1/check?url=https://my-app-git-feature.vercel.app" -H "X-API-Key: $SHOTLANE_API_KEY"

It returns a screenshot link, the HTTP status, plain-language issues and the raw diagnostics for each device. The default devices are iphone (393 px), ipad (820 px) and desktop (1280 px).

Setup: three minutes

1. Get a free API key at shotlane.dev (100 renders a month, no card).
2. In your repository, add it as the Actions secret SHOTLANE_API_KEY (Settings → Secrets and variables → Actions).
3. Add the workflow:

   mkdir -p .github/workflows
   curl -o .github/workflows/shotlane-check.yml https://shotlane.dev/sdk/shotlane-check.yml

4. Edit PAGES in the file to the paths that matter, for example "/ /pricing /signup". Commit and open a pull request.

When the preview goes live, the workflow posts a comment with a screenshot table per page and a list of problems per device. Each new deploy updates the same comment instead of adding another one. Screenshots are kept for 30 days, so the comment still shows them when someone reviews the PR next week. If a deploy isn't attached to a pull request, the results go to the job summary instead.

The workflow is plain YAML with curl, jq and the GitHub CLI, no third-party action, so you can read all of it before you add it: shotlane-check.yml.

Vercel previews behind Deployment Protection

New Vercel projects protect preview deployments with Vercel Authentication, so an outside browser gets a login page. Vercel's answer for automation is a bypass secret:

1. In the Vercel project, open Settings → Deployment Protection → Protection Bypass for Automation and create a secret.
2. Add it to the GitHub repository as VERCEL_AUTOMATION_BYPASS_SECRET.

The workflow then sends it as the x-vercel-protection-bypass header. Shotlane sends custom headers only to the preview's own host, never to third-party hosts on the page, and doesn't store or log them (details).

What it costs

One credit per page per device. Three pages on three devices is 9 credits per deploy. The free 100 credits a month cover about 11 such deploys; the $9 pack (2,000 credits) covers about 220. Failed renders aren't charged. Credits don't expire, so a quiet month costs nothing.

Using it from an AI agent

The same check is useful when an agent finishes a change: "deploy the preview, run the check, fix what it reports". Give the agent the curl command above (or the Python or Node SDK), and it gets screenshots it can look at plus a list of concrete problems with selectors. That beats asking a vision model to spot a 20-pixel overflow on its own.

Limits

• Public URLs only. Shotlane can't reach localhost or private networks, so this checks deploys, not your dev server. For local work, use a browser on your machine or a tunnel.
• Logged-in pages need cookies or headers in the request (headers, cookies options), which you may not want in CI. Start with public pages.
• Not a pixel-diff test. It finds problems that are wrong on any screen. To compare against a known-good version, Shotlane monitors mark changed pixels, or use a visual regression tool.