How to Configure Argos CI with a Monorepo and Multiple Apps

Configure Argos monorepo coverage by running a separate visual test setup for each app or package, tied to the same commit. Choose the Argos integration that matches each app’s test framework. Treat parallel workers inside one app as a separate concern: sharding combines screenshots from parallel test runs into one build, while monorepo build splitting separates app-level tests.

Argos’s Monorepos setup guide is the source of truth for exact configuration. The available research confirms the build-splitting model but did not expose the guide’s exact YAML, CLI flags, project-token arrangement, or path-filter examples. Those details should be taken from the current guide rather than guessed in a copy-paste workflow.

1. Map the apps and their test frameworks

Start with a short inventory. Include only apps or packages whose rendered UI needs its own visual coverage.

App or package	Test framework	Argos integration to investigate	Independent test run?
Web app A	Playwright	Playwright quickstart	Yes, if it has its own UI and test command
Component library	Storybook	Storybook quickstart	Usually a distinct visual target
Web app B	Cypress	Cypress quickstart	Yes, if independently tested
Other package	Other or custom runner	Generic CLI upload route	Depends on whether it produces screenshots

Argos’s quickstart index lists integrations for Playwright, Vitest, Storybook, Cypress, WebdriverIO, and Puppeteer, as well as a generic CLI upload path for other frameworks. Use the integration that matches how each app already creates screenshots; avoid introducing a second browser-testing stack solely to connect the app to Argos.

2. Choose the right split

Split by app or package

Use monorepo build splitting when apps have different test commands, dependencies, or visual coverage boundaries. Each app runs its own visual tests, while the runs remain associated with the shared commit. This lets a change in one app have a distinct test run from another app in the repository.

Shard one app only when its suite needs parallel workers

Sharding addresses a different boundary: one app’s visual suite is divided among parallel test nodes, and their screenshots are collected into one build. It is not a replacement for app-level separation. Decide the boundary first:

Several independently tested apps: follow the monorepo build-splitting guide.
One large app suite: follow the parallel-testing or sharding guide.
Several apps, one with a large suite: configure per-app splitting, then apply the documented sharding method to that app if needed.

Do not assume that combining every app into one test command or splitting every worker into a separate visual build will preserve the intended baselines. Check the current Argos documentation for how the chosen integration groups captures.

3. Follow the current setup guide for each app

Open the Argos monorepo setup guide and use its current build-splitting configuration.
For each app, follow the matching framework quickstart. Keep app-specific commands and dependencies scoped to that app.
Configure the CI workflow so each app’s visual job runs for the commit being evaluated. Use the guide’s documented project and build conventions; do not invent project-token names or CLI arguments.
Set up authentication using the current CI guidance. For GitHub Actions, review Argos’s OIDC instructions and enable the required workflow permission when using that method.
Run the workflow on a pull request and confirm that each intended app produces a visual test result associated with the same commit.
Make one intentional UI change in a test branch and verify that the expected app’s visual comparison is the one that reports it.

The guide may evolve, so copy exact workflow syntax and command options from its live version. The documentation index also separates monorepo setup from parallel testing, cached pipelines, and framework-specific setup; use the page for the feature you are configuring.

4. Configure GitHub Actions authentication carefully

Argos documents GitHub Actions OIDC as an authentication option. Its guidance says to enable OIDC in Project Settings → Authentication and give the workflow id-token: write. Where OIDC is used, Argos describes removing the long-lived ARGOS_TOKEN secret. Its May 2026 changelog also describes a tokenless fallback for cases where GitHub does not issue OIDC tokens, particularly fork pull requests.

Authentication behavior can depend on the event and repository context. Follow the current Argos documentation and its linked secure GitHub Actions guidance for the exact workflow configuration. Do not assume an older example that sets ARGOS_TOKEN is the only supported current setup, and do not print credentials in job logs.

5. Handle Storybook variants as separate visual modes

If an app’s Storybook must be checked in dark and light themes, multiple viewport sizes, or different locales, Argos Storybook modes can create separate snapshots with isolated baselines for each mode. This is useful when variants should be compared against their own expected rendering rather than against one mixed set of captures.

Decide which variants are meaningful before multiplying coverage. Each mode adds captures and review surface. Consult the current Storybook integration docs for the mode configuration syntax; the available research confirms the capability but not copyable syntax.

6. Decide what should run for a change

Monorepos can contain many apps, so consider whether every visual job needs to run on every change. Path-based filtering can reduce unnecessary CI work, but incorrect filters can silently skip coverage. The research dossier did not verify a specific Argos path-filter example, so implement filters using your CI provider’s documented syntax and validate them against the Argos monorepo setup.

Include shared component packages in the trigger logic for every app that consumes them.
Include shared styles, design tokens, test utilities, and build configuration where they can affect screenshots.
Run all relevant app jobs for changes to shared infrastructure.
Test the filter with changes to an app, a shared package, and unrelated documentation before relying on it.

Argos’s branch documentation describes automatic base-branch inference and auto-approved branches, with optional project-level customization. Check the current branch settings before adding custom branch rules; avoid duplicating defaults without a specific need.

7. Validate the result

Coverage: confirm that every intended app/package has a visual test path.
Association: verify all app-level runs correspond to the commit under review.
Isolation: change one app and confirm unrelated app baselines are not being treated as that app’s captures.
Parallel behavior: if sharding is enabled, confirm the shards are combined according to the current Argos instructions.
Variants: check that Storybook modes create the separate snapshots and baselines your team expects.
Authentication: test pull requests from branches and fork contexts relevant to your repository.
Filtering: exercise path filters with shared-package changes as well as app-local changes.

Common problems and fixes

Symptom	Likely cause	What to check
An app has no visual result	Its job did not run, the framework integration is missing, or screenshots were not uploaded.	Check the app’s workflow conditions, test command, and matching Argos quickstart.
Only one app appears covered	The pipeline is configured as one app’s integration rather than separate app-level runs.	Compare the workflow with the monorepo build-splitting guide and verify every app job runs.
Parallel captures do not form the expected build	App-level splitting and test sharding were mixed up, or the integration’s documented shard setup is incomplete.	Follow the separate parallel-testing guide for a single app and retain the monorepo split for app boundaries.
Fork pull request authentication fails	The event may not receive an OIDC token or available credentials.	Review Argos’s current OIDC and tokenless-fallback guidance and the workflow’s `id-token: write` permission.
Shared component changes are not checked by dependent apps	Path filters only match app-local paths.	Include shared dependency paths in the relevant jobs and test the filter with a shared-package change.
Theme or locale changes overwrite the wrong baseline	Variants may be captured without distinct Storybook modes.	Use the documented Storybook modes support and confirm each mode has the intended isolated baseline.
A workflow copied from a blog fails with current auth	The example may use older long-lived token instructions.	Compare it with current Argos OIDC documentation and the May 2026 authentication update.

Performance, reliability, and cost considerations

Splitting work by app can make CI scheduling more flexible, but it also creates more jobs and setup overhead. Sharding can parallelize one app’s suite; it adds coordination and should be introduced only when the suite’s runtime justifies it. No benchmark or runtime improvement is established here, so measure your own pipeline before and after changes.

Keep visual runs deterministic: pin the app build inputs where practical, wait for the UI state your tests need, and follow the framework integration’s guidance for stable screenshots. Shared fonts, images, browser versions, and environment variables can affect multiple apps. When a diff appears across many apps after a shared change, inspect those common inputs before updating baselines.

Argos is a managed cloud service, and the available official overview describes self-hosting as unsupported and undocumented. Check Argos’s current pricing and plan terms directly before estimating spend; this research does not establish current prices or per-capture billing rules.

Or skip the browser setup

If the task is to capture a page rather than compare app builds against visual baselines, ScreenshotNeo is a website screenshot API and MCP server. It does not replace Argos’s visual regression workflow. One GET request returns an image or PDF, and the API documentation covers its options.

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

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. 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; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.

Frequently asked questions

Does every app need a separate Argos project?

The confirmed recommendation is separate visual tests for each app or package within one commit. The research did not establish the exact project-token arrangement; follow the current monorepo guide for that choice.

Can apps use different test frameworks?

Yes. Select the matching Argos integration per app. The official quickstart lists several framework-specific options and a generic CLI path for other frameworks.

Is deployment preview required for monorepo visual testing?

No such requirement is established by the setup summary. Argos documents deployment previews as an adjacent capability; treat deployment as optional unless your workflow needs it.

Where can I find the exact YAML and CLI commands?

Use the live Monorepos setup guide and the quickstart for each app’s framework. Exact syntax is intentionally not reproduced here because it was not available for verification in the research.