GitHub Integration

Connect Argos to GitHub for automated visual testing on every pull request and merge queue run. Argos reads commit history to pick the right baseline build and reports results back to GitHub so you can ship with confidence.

What Argos does on GitHub

• Add commit and pull request checks, so Argos results can block merges when required in GitHub.

• Post pull request comments with the latest build results and links back to Argos.

• Analyze commit history to find the right merge base and select the correct baseline build for visual comparisons.

Why Argos needs repository access

Argos analyzes commit history to choose the right baseline build and posts commit statuses or pull request comments. Granting repository access lets Argos read commits, find merge bases, and report build results back to GitHub.

Choose your access level

• Full access (recommended) — Required for Merge Queue and baseline selection based on commit history.

• Limited access (no content) — Works for basic checks without reading repository content; Merge Queue is not supported. See GitHub Integration without Content Permission.

Use GitHub Connect to log in with your GitHub account, then install the Argos GitHub App to link repositories.

Install the Argos GitHub App

Argos provides a dedicated GitHub App that connects directly to your repositories, enabling real-time visual testing feedback on pull requests.

1. Visit the Argos app page on GitHub

2. Click on "Configure" and select the organization where you want to install Argos

3. Follow the prompts to complete the installation

Import a GitHub repository to Argos

1. Sign in to Argos and click on "Create a new project"

2. Choose GitHub as your provider, then click "Import your repository"

Update the Repositories Shared with Argos

1. Go to the Argos app page on GitHub and click "Configure"

2. Select the organization where you want to manage repository access

3. Under "Repository access," choose "Only select repositories" and select the specific repositories you wish to share with Argos

Required Argos status check in GitHub

Required GitHub App permissions

Argos needs the following permissions to operate:

• Contents — used to find a common commit ancestor between branches

• Statuses — used to add statuses to commits

• Pull requests — used to add comments in pull requests

• Actions — used to re-run an individual GitHub Actions workflow run when a check is retried from Argos

We take your security and privacy seriously. If you have any concerns or questions, please contact us.

Merge Queue support

When Argos runs inside the merge queue, it compares the queued changes against the merge base of all pull requests in the queue, ensuring that visual tests reflect the final merged state. This is supported out of the box with GitHub's native Merge Queue, and can be configured for custom merge queue systems as well.

GitHub Actions setup for GitHub Merge Queue

Listen to both pull_request and merge_group events so Argos uploads run for PR reviews and for queued merges:

.github/workflows/ci.yml

name: Visual tests

on:
  pull_request:
  merge_group:

jobs:
  argos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
      - run: npm ci
      - run: npm run test:e2e # Run E2E tests with Argos SDK integration
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }} # Argos token stored in GitHub Secrets

Custom merge queue systems

When you are using a merge queue system other than GitHub’s built-in Merge Queue (like Mergify), you can set ARGOS_MERGE_QUEUE_PRS to the comma-separated pull request numbers included in the queued build. This tells Argos to treat the upload as a merge queue build and use the right baseline for visual comparisons.

steps:
  - name: Upload screenshots to Argos
    env:
      ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
      ARGOS_MERGE_QUEUE_PRS: "101,102"
    run: npm exec -- argos upload ./screenshots

Use the pull request numbers included in the merge queue batch. Passing ARGOS_MERGE_QUEUE_PRS tells Argos to treat the upload as a merge queue build.

GitHub Integration without Content Permission

If you prefer to use Argos without granting full content access to your repositories, you can integrate via a more restricted setup.

Setting Up Argos with Limited GitHub Access

1. From the dashboard, select your team from the scope selector.

2. Select the Settings tab and go to the Integrations section.

3. Scroll to "GitHub without content access".

4. Click Install GitHub App.

GitHub without content access settings in Argos

1. On GitHub, choose the specific repositories where you want to install the Argos app.

Argos GitHub app without content access

1. Back in Argos, go to the Projects tab.

2. Click Create a new project at the top right.

3. Select Continue with GitHub (no-content access).

Argos GitHub app without content access

1. Choose the repository you want to connect.

GitHub Enterprise

GitHub Enterprise Cloud

GitHub Enterprise Cloud works out of the box. Follow the same GitHub App setup described above—no extra configuration is needed in Argos.

GitHub Enterprise Server (self-hosted)

Self-hosted GitHub Enterprise Server deployments are supported on the Argos Enterprise plan, which also includes SAML SSO and other advanced features. To upgrade to Enterprise, contact sales.