How to Connect Argos CI to a GitHub Actions Workflow

To connect Argos CI to GitHub Actions, link your GitHub repository to an Argos project, run screenshot-producing tests in a workflow, and let the Argos integration upload the captures for comparison. For current authentication, enable GitHub OIDC in Argos project settings and grant the workflow id-token: write. Playwright and Storybook use different capture integrations; choose the one that matches your test surface.

The workflow builds or serves the app, captures screenshots, uploads them to Argos, and exposes visual changes for pull request review. Argos’s newer guidance supports OIDC and a tokenless fallback when GitHub does not issue an OIDC token, such as for fork pull requests. See the Argos authentication update.

1. Connect your GitHub repository to Argos

1. Install or authorize the Argos GitHub App and grant access to the repository you want to test.
2. Link the repository to an Argos project using Argos’s onboarding flow.
3. In that project, open Settings → Authentication and enable GitHub OIDC.
4. Choose your capture integration below: Playwright for browser or end-to-end tests, Storybook for component stories, or a direct upload if your pipeline already generates screenshots.

The GitHub App connection lets Argos associate builds with repository activity and provide results for pull request review. Check the current Argos onboarding screen for project-specific setup, since the cited Playwright and Storybook guides predate the newer OIDC option. The Playwright guide and Storybook guide describe their respective capture integrations.

2. Configure the workflow’s authentication

For GitHub Actions, add the narrowly scoped id-token: write permission. With OIDC enabled in Argos, its SDK can use GitHub’s signed workflow identity. Remove ARGOS_TOKEN from the job when using OIDC. Argos says that when GitHub does not issue an OIDC token, it can fall back to a tokenless flow that verifies the in-progress workflow run.

permissions:
  contents: read
  id-token: write

Keep any other permissions your repository’s existing workflow actually needs, but do not grant broad write permissions just to upload screenshots. The Argos changelog identifies id-token: write as the OIDC permission. Its fallback is intended to cover cases such as fork pull requests where OIDC is unavailable.

Older Argos framework guides show a long-lived ARGOS_TOKEN secret. Treat that as a legacy or fallback setup: the May 2026 guidance recommends OIDC where available and says to remove the token from the job for that path. Do not assume the older examples are current authentication instructions.

3. Playwright: capture pages in browser tests

Use the Playwright integration when you want screenshots from browser or end-to-end tests. The Argos Playwright guide uses @argos-ci/playwright, its reporter, and the argosScreenshot helper. The example below assumes a Node project with Playwright already configured and an application available at http://localhost:3000 when the test runs.

Install and configure the reporter

npm install --save-dev @argos-ci/cli @argos-ci/playwright

// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  reporter: process.env.CI
    ? [["list"], ["@argos-ci/playwright/reporter"]]
    : [["list"]],
});

Add a screenshot test

// tests/homepage.spec.ts
import { test } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";

test("homepage visual snapshot", async ({ page }) => {
  await page.goto("http://localhost:3000/");
  await argosScreenshot(page, "homepage");
});

Make sure your workflow starts the application before running this test, or change the URL to a preview environment reachable from the runner. Use stable test data and wait for important page content before capturing so that screenshots do not depend on asynchronous loading.

GitHub Actions workflow

Save this as .github/workflows/visual-tests.yml. Pin the Node version to the one your project supports; action versions shown here are examples and should be checked against your repository’s current setup.

name: Visual tests

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

jobs:
  playwright:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers and system dependencies
        run: npx playwright install --with-deps chromium

      # Replace this with your app's actual build and server commands.
      - name: Build application
        run: npm run build

      - name: Start application
        run: npm run start &

      - name: Wait for application
        run: npx wait-on http://127.0.0.1:3000

      - name: Run visual tests
        run: npx playwright test

If your app is started by a test fixture or a Playwright webServer configuration, omit the separate start and wait steps. The essential sequence is checkout, locked dependency installation, browser installation, app availability, then the test command that invokes the Argos reporter.

4. Storybook: capture component stories

Choose Storybook when you want coverage of isolated components and stories. The Argos Storybook example uses the Storybook test runner and @argos-ci/storybook; its postVisit hook captures each visited story. These package and runner details come from Argos’s October 2024 guide, so check your Storybook version’s compatibility and current setup instructions before adopting them.

Install and set up the capture hook

npm install --save-dev @argos-ci/cli @argos-ci/storybook @storybook/test-runner

// .storybook/test-runner.ts
import { argosScreenshot } from "@argos-ci/storybook";
import type { TestRunnerConfig } from "@storybook/test-runner";

const config: TestRunnerConfig = {
  async postVisit(page, context) {
    await argosScreenshot(page, context);
  },
};

export default config;

Make sure the Storybook test runner writes its screenshots where the upload integration expects them. The guide’s example uses a screenshots directory and recommends keeping generated screenshots out of version control. Follow the scripts and command syntax appropriate to your Storybook and package manager versions.

GitHub Actions workflow for Storybook

This example builds Storybook, serves the static output, waits for it to be reachable, then runs the test runner. The server command assumes the output directory is storybook-static and that http-server, wait-on, and concurrently are available in your development dependencies.

name: Storybook visual tests

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

jobs:
  storybook:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browser dependencies
        run: npx playwright install --with-deps chromium

      - name: Build Storybook
        run: npm run build-storybook

      - name: Serve Storybook and run tests
        run: |
          npx concurrently -k -s first \
            "npx http-server storybook-static --port 6006 --silent" \
            "npx wait-on http://127.0.0.1:6006 && npm run test-storybook"

If your Storybook build directory differs, change storybook-static. If your project’s test command performs the Argos upload as a separate step, include it after the screenshot-producing runner. Use the current Argos instructions for that integration; do not add the old guide’s token environment variable when OIDC is configured.

5. Existing screenshot directory: upload with the SDK

If your job already creates screenshot files, Argos’s Node.js SDK can upload a directory rather than integrating capture into Playwright or Storybook. The SDK reference demonstrates the upload call with a root folder and file glob. The example below shows the documented upload shape; follow current authentication guidance for your CI environment.

import { upload } from "@argos-ci/sdk";

await upload({
  root: "./screenshots",
  files: ["**/*.png"],
});

The SDK example documents ARGOS_TOKEN as an environment-based option, but that should not be read as a requirement for every current GitHub Actions integration. Prefer the current OIDC flow where supported. See the authentication changelog and the Playwright workflow example.

6. Review visual changes in the pull request

1. Open the pull request’s checks or Argos result.
2. Compare changed screenshots with the existing baseline.
3. Approve expected visual changes, such as an intentional redesign.
4. For unexpected changes, reproduce the issue locally and fix the code or stabilize the page before updating the baseline.

Argos provides screenshot comparisons for review in the pull request workflow. The point of the check is to make visual changes visible; a changed screenshot is a prompt to review, not automatic proof of a defect. See the Argos Playwright guide for its described pull request review flow.

Configuration choices and edge cases

Choice	Use it when	Watch for
Playwright integration	You need visual coverage from browser or end-to-end tests.	The application must be reachable by the test runner, and page state should be deterministic.
Storybook integration	You want component and story coverage.	Build the correct Storybook output directory and serve it before the test runner starts.
Direct SDK upload	A custom process already writes screenshot files.	Ensure the files exist in the job and the glob matches their extensions and nested paths.
OIDC	GitHub issues an identity token for the run.	Enable it in Argos project authentication and set id-token: write.
Tokenless fallback	OIDC is unavailable, including the fork PR case described by Argos.	Argos verifies the workflow run; avoid adding a long-lived secret solely to handle forks unless your current project instructions require it.

• Fork pull requests: secrets are generally unavailable to workflows from forks. Argos documents tokenless fallback when GitHub does not provide OIDC; avoid changing the workflow to expose secrets to untrusted code.
• Multiple reporters: preserve your existing Playwright reporters when adding Argos. The sample includes the list reporter and Argos reporter on CI.
• Multiple branches: the sample runs on pull requests and pushes to main. Adapt triggers to your default branch and release workflow.
• App startup: a test that navigates to localhost needs an application server running in that same job. Wait on an HTTP endpoint, not just a fixed sleep, where possible.
• Visual stability: use consistent browser versions, fonts, viewport, fixtures, and data. Disable or wait for animations and content that changes on every run.
• Package-manager differences: the examples use npm. Substitute the locked install command for pnpm or Yarn and ensure its lockfile is committed.
• Version drift: the cited Playwright setup article is from 2023, and the Storybook article is from 2024. Their action versions are examples, so review current GitHub Action and framework documentation before copying them.

Performance, reliability, and cost

Browser installation and building the app or Storybook are usually unavoidable work in this pipeline; reduce repeated work with the package manager’s supported dependency cache and install only the browser engines your tests use. Keep the visual suite focused on meaningful routes or stories, and parallelize only when your server, fixtures, and capture integration remain deterministic.

Reliability depends heavily on reproducible rendering: use the same browser and operating environment, wait for the page’s meaningful ready state, and avoid volatile timestamps, randomized content, and network-dependent third-party widgets. If captures fail only in CI, inspect app startup, browser installation, fonts, and test timing before changing the baseline.

The provided Argos integration sources do not give pricing or a per-capture cost, so this guide makes no cost estimate. Check the current Argos plan and usage terms in your account before setting a capture volume. For workflow costs, avoid unnecessarily rebuilding Storybook or installing every browser for each job if your pipeline can safely reuse artifacts.

Common errors and fixes

Symptom	Likely cause	Fix
Upload authentication fails on internal pull requests	OIDC is not enabled in the Argos project or the workflow lacks its identity-token permission.	Enable GitHub OIDC in Project Settings → Authentication and add id-token: write under workflow permissions.
Fork pull request cannot access ARGOS_TOKEN	GitHub does not expose repository secrets to an untrusted fork workflow.	Use Argos’s documented tokenless fallback when OIDC is unavailable; do not expose a secret to fork code.
Playwright reports connection refused	The app server did not start, is listening on another port, or tests ran before it was ready.	Start the app in the job, confirm its bind address and port, and wait for its URL before running tests.
No screenshots arrive in Argos	The test did not invoke the Argos reporter/helper, or the workflow skipped the upload step.	Check the Playwright reporter configuration or Storybook postVisit, then confirm the capture command ran in CI.
Storybook test runner cannot connect	The static server is serving the wrong directory or did not start.	Verify the build output path, serve that path, and make the runner wait for the correct local URL.
SDK uploads zero files	The screenshot path or file pattern does not match generated files.	List the output directory in the job logs and adjust root and files to the actual paths.
Visual diffs change between identical commits	Rendering depends on animation, dynamic data, timing, fonts, browser version, or external resources.	Stabilize fixtures and page readiness, hide or disable volatile elements, and standardize the CI browser environment.

Or skip the browser setup

For one-off website captures or automation that needs an image rather than a visual regression baseline, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. It can accept cookie and consent banners like a visitor and remove 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf.

cURL example (see the ScreenshotNeo API docs):

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

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
const bytes = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

Its free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.

FAQ

Does connecting Argos replace Playwright or Storybook?

No. Those tools render and test your application or stories; the Argos integrations capture and upload screenshots for visual comparison.

Will Argos run automatically on every pull request?

Only when your workflow trigger includes pull requests and the relevant job runs successfully. The examples use a pull_request trigger.

Do I need to commit screenshots to Git?

The cited integrations upload captures from CI to Argos; the Storybook guide says generated screenshots should be ignored by Git. Follow the selected integration’s current output and upload instructions.

Can I use this with a custom screenshot script?

Yes. If the script writes image files, use the Argos SDK or CLI upload path supported by your current project configuration instead of a framework-specific capture helper.

Sources: Argos GitHub Actions authentication update; Argos Playwright guide; Argos Storybook guide.