Connect your repository to Argos, run the screenshot-producing tests in GitHub Actions, and let Argos compare the uploaded images with a baseline for pull-request review. For current GitHub Actions authentication, enable OIDC in the Argos project and grant the workflow id-token: write; Argos documents a tokenless fallback when GitHub does not issue an OIDC token, including for fork pull requests. Then choose the capture integration that matches your app: Playwright for browser tests or Storybook for component stories.
How the Argos and GitHub Actions connection works
GitHub Actions runs your app’s screenshot-generating tests and sends the results to Argos. Argos compares those screenshots with the project’s baseline and makes visual changes available as pull-request checks or diffs. Reviewers can approve expected UI changes or investigate unintended regressions. See the Argos documentation overview for the workflow lifecycle and review model.
As an Amazon Associate I earn from qualifying purchases.
The connection has three parts: repository access through the Argos GitHub App, screenshot capture in your test job, and authentication for the upload. The capture step varies by test surface; authentication should follow Argos’s current GitHub Actions guidance rather than older guide snippets that rely on a persistent token.
Choose the screenshot capture method
| Use case | Integration | What it captures |
|---|---|---|
| Browser or end-to-end tests | @argos-ci/playwright and its reporter/helper |
Pages or states visited by Playwright tests |
| Storybook component testing | @argos-ci/storybook with @storybook/test-runner |
Stories rendered by Storybook’s test runner |
| Existing screenshot pipeline or custom setup | Argos Node.js SDK or CLI upload | Screenshot files your pipeline already produces |
Choose based on where your UI is rendered. Playwright is appropriate when visual coverage belongs in browser tests; Storybook is appropriate when you want to compare component stories. Argos’s older guides document the framework patterns, while the current auth instructions are newer: the Playwright guide dates to January 24, 2023, and the Storybook guide to October 29, 2024.
#1 Best Overall
Connect the GitHub repository to Argos
- Install or authorize the Argos GitHub App and grant it access to the repository you want to test. The app connects the repository and enables Argos to report results on pull requests.
- Complete the Argos project onboarding and check the current project settings. Product settings can change, so use the options shown for your account rather than assuming labels or plan details from an older guide.
- In the Argos project, open Settings → Authentication and enable GitHub OIDC for the workflow authentication path described below.
Configure current GitHub Actions authentication
Argos’s May 11, 2026 guidance recommends GitHub OIDC instead of keeping a long-lived ARGOS_TOKEN secret in the job. Enable OIDC in the project’s Settings → Authentication, then grant the workflow the specific permission id-token: write. Argos uses the GitHub-signed identity when GitHub provides an OIDC token.
permissions:
contents: read
id-token: writeThis example keeps repository contents read-only while allowing the job to request an identity token. Retain other permissions only when your workflow genuinely needs them; do not grant broad write access just to upload screenshots. Check the permissions required by the rest of your repository workflow as well.
Argos says it falls back to tokenless authentication when GitHub does not issue an OIDC token, especially for fork pull requests. Its changelog says that fallback verifies the in-progress workflow run with GitHub before issuing a short-lived token. Do not add a long-lived token to fork jobs as a workaround unless Argos’s current project guidance specifically requires it.
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 minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOlder Argos framework examples pass ARGOS_TOKEN from GitHub Secrets. Those examples predate the May 2026 OIDC guidance. When using OIDC, remove ARGOS_TOKEN from the job as Argos instructs; do not mix the old secret-based setup into the OIDC path by default.
Playwright setup for GitHub Actions
The Playwright integration uses @argos-ci/playwright, an Argos reporter, and the argosScreenshot helper in tests. The package and reporter approach is documented in Argos’s Playwright and GitHub Actions guide. Install the packages using the package manager and lockfile already used by your project; the guide also installs @argos-ci/cli.
npm install --save-dev @argos-ci/cli @argos-ci/playwrightAdd the Argos reporter alongside your existing Playwright reporters, and capture a stable state in the test. Keep your normal test assertions; the screenshot helper adds visual capture rather than replacing functional checks.
// playwright.config.ts
import { defineConfig } from "@playwright/test";
export default defineConfig({
reporter: ["list", "@argos-ci/playwright/reporter"],
});// Example test
import { test } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";
test("homepage visual state", async ({ page }) => {
await page.goto("http://127.0.0.1:3000");
await argosScreenshot(page, "homepage");
});Update the URL and test state for your app. Ensure the app server is running before the test starts, and capture deterministic UI states rather than transient loading screens. The following workflow is a structural example: choose action versions supported by your repository and current GitHub documentation instead of copying version references from Argos’s January 2023 article.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →name: Visual tests
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
id-token: write
jobs:
playwright:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npx playwright install --with-deps
- run: npm run build
- run: npm run start -- --port 3000 &
- run: npx wait-on http://127.0.0.1:3000
- run: npm exec playwright testThe action references and Node version above illustrate the job shape, not a current version recommendation. Validate them against your project’s supported runtime and current action releases. Add a server-start/wait step only if your test suite requires a locally served app; the workflow must make the target UI reachable before screenshots are taken.
Storybook setup for GitHub Actions
For Storybook, the documented integration combines @argos-ci/storybook with @storybook/test-runner. Argos’s Storybook and GitHub Actions guide configures a test-runner hook to capture each visited story after it renders.
npm install --save-dev @argos-ci/cli @argos-ci/storybook @storybook/test-runner// .storybook/test-runner.ts
import { argosScreenshot } from "@argos-ci/storybook";
export default {
async postVisit(page, context) {
await argosScreenshot(page, context);
},
};The workflow needs to build Storybook, serve the generated storybook-static directory, wait until it is available, and run the test runner. Use your Storybook version’s supported build and test-runner commands; the commands below show the sequence rather than prescribing a version-specific script name.
name: Storybook visual tests
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
id-token: write
jobs:
storybook:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run build-storybook
- run: npx http-server storybook-static -p 6006 &
- run: npx wait-on http://127.0.0.1:6006
- run: npm run test-storybookThe Storybook guide’s original workflow passes ARGOS_TOKEN from GitHub Secrets. For a current OIDC-enabled setup, follow the authentication steps above instead and remove that token from the job. Confirm your project scripts and test-runner version because Storybook commands can vary by setup.
Upload screenshots from a custom pipeline
If your workflow already creates screenshots without the Playwright or Storybook integration, use the Argos Node.js SDK to upload the directory. The SDK reference shows an upload call with a root directory and glob pattern, and uses ARGOS_TOKEN by default when supplied through the environment. This is an SDK detail; it does not mean every current GitHub Actions integration requires a long-lived secret.
Best Value
import { upload } from "@argos-ci/core";
await upload({
root: "./screenshots",
files: ["**/*.png"],
});Install and configure the SDK according to the Argos Node.js SDK reference. Ensure the screenshots exist in the specified directory in the same job, or transfer them between jobs as an artifact before invoking the upload.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Review visual changes in the pull request
- Open the Argos check or result linked from the pull request.
- Compare changed screenshots with the current baseline, including the affected page or story and the visual difference.
- Approve the changes when they are intentional; otherwise fix the UI or test setup and rerun the workflow.
Visual diffs are evidence for review, not a substitute for deciding whether the change is correct. A changed baseline should correspond to an intentional UI update.
Troubleshoot common failures
| Symptom | Likely cause | What to check |
|---|---|---|
| Upload reports authentication failure | OIDC is not enabled for the Argos project, or the workflow lacks the identity-token permission. | Verify Settings → Authentication and confirm the job has id-token: write. Avoid retaining the old token configuration in the OIDC job. |
| Fork pull request cannot obtain an OIDC token | GitHub may not issue an OIDC token in this context. | Argos documents a tokenless fallback for runs without OIDC, including fork pull requests. Check the Argos result and current authentication setup rather than exposing a persistent secret to fork code. |
| No screenshots appear in Argos | The screenshot test did not run, the reporter/helper was not configured, or the upload step cannot see the output files. | Check the test command’s logs, reporter configuration, screenshot directory, and whether files were generated in the upload job. |
| Tests fail before capture because the page is unavailable | The app or Storybook server is not running or is not ready when tests start. | Start the expected server and wait for its local URL before running Playwright or the Storybook test runner. |
| Storybook upload produces no useful comparisons | The test runner is not visiting stories or the postVisit capture hook is absent. |
Confirm the runner is configured for the Storybook build and that argosScreenshot(page, context) runs after each story visit. |
| Visual diffs change between runs unexpectedly | The rendered state may depend on timing, dynamic data, fonts, animation, or environment differences. | Make test data and page state deterministic, wait for the intended UI to render, and keep the runtime/browser setup consistent across runs. |
| Copied workflow uses incompatible actions or scripts | Examples in older Argos guides may not reflect your current repository or action versions. | Check current GitHub action releases, your framework’s supported commands, and the lockfile before updating the workflow. |
Performance, reliability, and cost considerations
- Run only the visual tests that cover the states you need; broader browser or story coverage increases CI work because more screenshots must render and upload.
- Keep the app build, browser dependencies, and screenshot capture in a reproducible environment. A missing server, browser, or generated screenshot directory commonly prevents a useful comparison.
- Use the framework integration when it fits your test surface; use direct SDK upload when screenshots already come from a custom pipeline.
- Argos’s reviewed setup instructions do not state a numeric upload-time guarantee, comparison accuracy rate, or cost for this integration. Check Argos’s current account and plan details for applicable service and pricing terms.
Or skip the browser setup
If your immediate goal is to produce a website screenshot from code without configuring browser automation, ScreenshotNeo offers a screenshot API and MCP server. It does not replace Argos’s baseline-based visual regression workflow; it is an alternative way to capture a page. One GET request returns an image or PDF:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Does Argos require an ARGOS_TOKEN secret in GitHub Actions?
Not for the current OIDC flow when GitHub provides an OIDC token; Argos documents a tokenless fallback when one is unavailable.
Can Argos capture screenshots without Playwright or Storybook?
Yes. A custom pipeline can upload an existing screenshot directory with the Argos Node.js SDK or CLI.
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.
