# 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](/docs/learn/review-workflow/pull-request-comments.md) 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](/docs/learn/platform-fundamentals/baseline-build.md) for visual comparisons.

### Why Argos needs repository access

Argos analyzes commit history to choose the right [baseline build](/docs/learn/platform-fundamentals/baseline-build.md) 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](#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](https://github.com/apps/argos-ci)
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](https://github.com/apps/argos-ci) 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](/files/ce64491dd225f415224b6f02c87bb9bd17d8c7e7)

### 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](https://argos-ci.com/contact).

### 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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-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:

{% code title=".github/workflows/ci.yml" %}

```yaml
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
```

{% endcode %}

#### Custom merge queue systems

When you are using a merge queue system other than GitHub’s built-in Merge Queue (like [Mergify](https://mergify.com/)), 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.

```yml
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](/files/9350ccd345be129222c75f6f5d7949db0984bd79)

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

![Argos GitHub app without content access](/files/5100dd66497e4570a33028213c175a2f8fa90a00)

6. Back in Argos, go to the **Projects** tab.
7. Click **Create a new project** at the top right.
8. Select **Continue with GitHub (no-content access)**.

![Argos GitHub app without content access](/files/5fb0e114c4770054ce4a18ce3de7709534290777)

9. 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](mailto:contact@argos-ci.com).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://argos-ci.com/docs/learn/integrations/github-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.