How to Use Argos CI with a Private GitHub Repository

To use Argos CI with a private GitHub repository, sign in to Argos with GitHub, install or authorize its GitHub integration for the account that owns the repository, and ensure the private repository is included in the installation’s repository scope. Then connect the repository in Argos and add screenshot capture and upload to your CI workflow. For GitHub Actions, use an ARGOS_TOKEN secret as shown in Argos’s setup guide, or use Argos’s newer GitHub OIDC authentication when it is enabled for your project.

This guide uses Storybook to make the workflow concrete. If your project captures screenshots with a different supported setup, keep your existing capture and test commands and adapt the workflow’s install, build, and upload steps. The key private-repository details are GitHub App installation scope, organization approval, and how the workflow authenticates.

1. Connect the private repository to Argos

Sign in to Argos using the GitHub account that can access the target repository.
Authorize Argos when GitHub prompts you, and install its GitHub App on the account or organization that owns the repository if prompted.
On GitHub’s installation screen, select the target private repository. If the installation is restricted to selected repositories, the repository must be explicitly included. An app installation’s repository selection limits which repositories it can access. See GitHub’s documentation on authorizing and installing GitHub Apps.
Review the permissions shown by GitHub before confirming. GitHub recommends minimum permissions for apps; Argos’s requested permission list can change, so use the live installation screen as the source of truth rather than assuming a fixed set. See GitHub’s GitHub App permissions guide.
In the Argos dashboard, add the repository and follow its project setup instructions. Confirm that the selected Argos project is linked to the intended GitHub repository.

For an organization-owned repository, the person installing the app may need organization-owner approval, depending on the organization’s policy. If the repository is not listed, check which GitHub account is signed in, whether the app is installed on the owning organization, and whether the repository is included in the installation scope.

2. Add Storybook screenshot capture

Argos’s published Storybook example uses the Storybook Test Runner and Argos SDK to capture each story. Install the packages in your project:

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

Configure the test runner in .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;

The hook captures a screenshot after each story is visited. Run the test runner locally with npx test-storybook and check that the stories load and screenshots are produced. Keep generated screenshots out of version control if your project’s setup writes them into the repository; Argos’s guide recommends adding its local screenshot output directory to .gitignore.

Add scripts like these to package.json, adjusting the Storybook build command to match your project:

{
  "scripts": {
    "build-storybook": "build-storybook",
    "test-storybook": "NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules test-storybook",
    "upload-screenshots": "npm exec argos -- upload screenshots --build-name storybook"
  }
}

The Node options shown follow Argos’s published example. If your Storybook or test-runner version requires a different invocation, use the commands supported by the versions installed in your repository.

3. Configure GitHub Actions

The workflow below follows Argos’s documented Storybook pattern: install dependencies, install browser support, build Storybook, serve it locally, run the test runner, and upload the screenshots. It runs for pull requests and pushes to main.

# .github/workflows/storybook-tests.yml
name: Storybook Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
      - name: Install dependencies
        run: npm ci
      - name: Install Playwright browsers
        run: npx playwright install --with-deps
      - name: Build Storybook
        run: npm run build-storybook -- --quiet
      - name: Serve Storybook and run tests
        run: |
          npx concurrently -k -s first -n "SB,TEST" -c "magenta,blue" \
            "npx http-server storybook-static --port 6006 --silent" \
            "npx wait-on tcp:127.0.0.1:6006 && npm run test-storybook && npm run upload-screenshots"
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

This example assumes the repository has .nvmrc, a package lockfile, and the listed commands available. If your lockfile or package manager differs, update the install command to the equivalent deterministic install for your project. If Storybook builds to a different directory or port, make the server command and readiness check match. The Argos guide’s published workflow uses npm install --frozen-lockfile; for npm projects, npm ci is the corresponding lockfile-based install command.

4. Choose token or OIDC authentication

Option A: Store an Argos token as a GitHub Actions secret

In the Argos project settings, obtain the project’s ARGOS_TOKEN using the setup instructions shown for your project.
In GitHub, open the repository’s Settings → Secrets and variables → Actions, create a repository secret named ARGOS_TOKEN, and paste in the value.
Keep the secret reference in the upload job’s environment, as in the workflow above. Do not hard-code the token in workflow YAML, source code, or logs.

This is the token-based method in Argos’s Storybook and GitHub Actions guide. Repository secrets are available only according to GitHub’s secret and event rules. In particular, do not assume a workflow triggered by an external fork can read the base repository’s secrets.

Option B: Use GitHub OIDC where supported

Argos announced GitHub OIDC authentication on May 11, 2026. Its documented setup is to enable GitHub OIDC in the Argos project’s authentication settings, grant the workflow id-token: write, and remove ARGOS_TOKEN from that job. Argos says it validates GitHub’s short-lived identity against the linked repository and workflow. Follow the current Argos project instructions for the workflow and SDK versions you use: Argos’s OIDC authentication announcement.

For example, add the permission at workflow or job level as appropriate:

permissions:
  contents: read
  id-token: write

Grant only the permissions your job needs. With OIDC configured, remove the ARGOS_TOKEN environment mapping for that job; do not keep a long-lived secret in place unless your current Argos setup explicitly requires it.

Method	What you configure	Considerations
Argos token	Save `ARGOS_TOKEN` as a GitHub Actions repository secret and pass it to the upload job.	Use the documented setup for your project. Treat the token as a credential and keep it out of logs and source control.
GitHub OIDC	Enable OIDC in Argos project settings and grant `id-token: write` to the workflow.	Uses a short-lived GitHub-signed identity when supported and configured. Follow Argos’s current instructions for event behavior.

5. Handle pull requests, including forks

Start with the events you need: the example runs on pull requests and pushes to main. Then confirm that uploads appear in the correct Argos project and that the expected check or visual review is associated with the pull request.

Fork pull requests need particular care because GitHub does not generally expose repository secrets to workflows from forks. Argos’s May 2026 announcement describes a tokenless fallback for workflows where GitHub does not issue OIDC tokens, especially fork pull requests. It says Argos verifies the repository, commit, branch, and in-progress workflow run through GitHub’s API before issuing a short-lived token. This behavior depends on Argos’s current support and project configuration; verify it against the live documentation for your workflow and organization policies rather than extending it to every event combination.

Test an internal pull request and a push to the default branch.
If outside contributors use forks, test a fork pull request without exposing secrets to untrusted code.
Confirm the workflow’s permissions and trigger behavior with your organization’s Actions policy.
Check that a pull request report is attached to the intended repository and Argos project.

Avoid switching to a privileged pull request trigger solely to make a secret available to fork code. Keep credentials out of untrusted pull request execution and use the authentication flow Argos currently documents for that event.

6. Verify the integration

Run the Storybook test command locally and fix any missing browser, story, or build configuration.
Open a pull request that changes a visible component and confirm the workflow completes.
Inspect the Actions log for the Storybook build, test-runner, and upload steps. Never print a token or other credential to debug authentication.
Open the resulting Argos build and confirm it belongs to the intended project and commit.
Push to main and verify the branch workflow behaves as expected.

Common problems and fixes

Symptom	Likely cause	Fix
Private repository is missing from Argos	The wrong GitHub account was used, the app is installed on a different account, or the repository is outside the selected installation scope.	Check the repository owner, switch to the account with access, and review the GitHub App installation’s selected repositories. Ask an organization owner to approve or install it if required by policy.
GitHub blocks the installation or asks for approval	Organization policy restricts third-party app installation or approval.	Have an organization owner review the app and requested permissions on GitHub’s installation screen. Do not assume a personal authorization also installs the app for the organization.
Upload reports missing or invalid credentials	The secret name, value, or job environment is incorrect, or the job is using a different authentication method than Argos expects.	For token auth, verify the exact secret name `ARGOS_TOKEN`, its project value, and the upload step’s environment. For OIDC, confirm it is enabled in Argos and the job has `id-token: write`; remove the token mapping if following Argos’s OIDC setup.
Fork pull request cannot access the token	GitHub withholds repository secrets from fork workflows.	Do not expose the secret to untrusted fork code. Check Argos’s current tokenless/OIDC instructions and test the supported flow for your repository.
Storybook test runner cannot connect	The server did not start, the port or build directory is wrong, or the readiness check points to another address.	Confirm that `storybook-static` exists, keep the server and `wait-on` host and port aligned, and review the server output for build errors.
No screenshots are uploaded	The test runner did not visit stories, the Argos post-visit hook is absent, or the upload command did not run.	Run `npx test-storybook` locally, confirm `argosScreenshot` is called by the test-runner hook, and inspect whether the combined CI command reached the upload step.
Browser or dependency install fails	The browser version, system dependencies, Node version, or package-lock state does not match the workflow.	Use the Node version expected by the project, commit the correct lockfile, and install the browser dependencies required by your test setup.
Upload appears under a different project	The token or workflow configuration points to another Argos project, or the wrong repository was connected.	Recheck the Argos repository/project selection and credentials, then rerun the workflow and inspect the commit and project association.

Performance, reliability, and cost

CI time depends on your dependency install, Storybook build, browser setup, and number of stories. Cache dependencies using your existing GitHub Actions approach if appropriate, avoid rebuilding unrelated assets, and keep the screenshot job’s timeout long enough for the project without masking a hung server. The example’s 60-minute job timeout is a configuration choice in Argos’s guide, not a performance guarantee.

For reliability, use a lockfile-based install, align the Storybook output directory and serving port, and make the workflow’s readiness check wait for the actual local server. Keep the capture and upload commands visible as separate stages when diagnosing failures. Authentication behavior can differ by event, especially for forks, so exercise the exact pull request types your repository receives.

Argos’s pricing page currently lists a free Hobby plan with up to 5,000 screenshots and GitHub integration, and a Pro plan starting at $100 per month with 35,000 screenshots included. The same page lists private deployment protection under Pro, but those details do not establish that every private-repository configuration or feature is included on Hobby. Check the current Argos pricing page and your project’s entitlement before relying on a plan feature; pricing and limits can change.

Or skip the browser setup

If the task is to capture a page as an image or PDF rather than compare application builds for visual regressions, ScreenshotNeo provides a website screenshot API and MCP server for developers. One GET request can return a PNG, JPEG, WebP, or PDF. It does not replace Argos’s repository-linked visual comparison workflow; it is useful when you need a clean capture of a URL.

For example, use cURL to save a WebP screenshot:

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

See the ScreenshotNeo API documentation for request options and response details. Cookie and consent banners are accepted like a visitor and removed along with 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Does Argos work with a private GitHub repository?

The documented setup is to authorize Argos, add the repository in the dashboard, and configure the repository’s CI upload. Ensure the GitHub integration has access to the private repository and check current plan entitlements for the features you need.

Do I need Storybook?

No. Storybook is the example used here because Argos publishes a Storybook and GitHub Actions setup. Adapt the capture and upload steps to your existing supported test stack.

Should I use an Argos token or OIDC?

Use the method currently enabled and documented for your Argos project. The token is in Argos’s published workflow guide; OIDC is a later announced option that avoids storing a long-lived token when configured and supported.

Can fork pull requests upload screenshots?

Argos documents a tokenless fallback for certain workflows where GitHub does not issue OIDC tokens, including fork pull requests. Confirm the current supported behavior for your project, event, and organization configuration.