> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Connect the GitHub App for automatic PR reviews, or use GitHub Actions workflows for reviews and test plans.

QA.tech connects to GitHub in two ways. They can be used together.

| | **GitHub App** | **GitHub Actions** |
| :- | :- | :- |
| **What it does** | Automatic review when a pull request opens or updates | Workflows you add yourself |
| **Where to configure** | Install and map the repository on this page | Workflow YAML in your repo |
| **Pull request testing** | [GitHub pull request testing](/pr-testing/github#github-app) | [Change Review Action](/pr-testing/github#change-review-action) |
| **Regression testing** | Not this path | [Test Run Action](/regression-testing/github) |

This page is the install and settings reference for the GitHub App. How a review starts, what it posts, and the check it creates are on [GitHub pull request testing](/pr-testing/github). What a review does on every CI is on [How a review works](/pr-testing/overview#how-a-review-works).

<CardGroup cols={2}>
  <Card title="Pull request testing" icon="code-pull-request" href="/pr-testing/github">
    The GitHub App and the Change Review Action review a pull request.
  </Card>

  <Card title="Regression testing" icon="clipboard-list" href="/regression-testing/github">
    The Test Run Action runs a test plan.
  </Card>
</CardGroup>

## How to Set It Up

<Steps>
  <Step title="Install GitHub App">
    Go to [Settings → Integrations → GitHub App](https://app.qa.tech/current-project/settings/integrations/github-app) and connect GitHub. Follow the OAuth flow to grant access to your repositories. The GitHub account is shared by every project in the organization.
  </Step>

  <Step title="Configure Repository">
    On the same page, select the repository you want to enable PR reviews for.
    **PR reviews are enabled automatically** once you select a repository.
    **Optional:** Add review context to guide the agent (e.g., "Focus on security
    vulnerabilities" or "Validate accessibility standards"). This appears in the
    integration settings.
  </Step>

  <Step title="Code access (on by default)">
    Saving a new repository mapping turns **Enable code access** on. Chat and PR
    reviews can then clone and search source. Turn the toggle off if you do not
    want cloning. Existing mappings created before this default stay off until you
    enable them. See [Code access](#code-access).
  </Step>

  <Step title="Configure Preview Deployments (if needed)">
    If you use Vercel, Netlify, Render, Railway, or Fly.io, your preview
    deployments are detected automatically.

    <Note>
      QA.tech creates preview environment records in your project when it detects
      your preview deployments. Your CI/CD platform handles the actual deployment.
      QA.tech tests against the preview URLs. See [Preview
      Environments](/core-concepts/applications-and-environments#preview-environments).
    </Note>

    **For GitHub Actions or other custom CI/CD:** QA.tech finds preview URLs
    through GitHub's [Deployments
    API](https://docs.github.com/en/rest/deployments/deployments). After your
    workflow deploys, it must create a deployment on the PR head commit, set the
    latest status to `success`, and put the preview URL in `environment_url`.
    Follow [GitHub Deployments](/configuration/github-deployments) for the Actions
    recipe, required fields, and permissions. Any CI that can call the GitHub REST
    API can create the same records. For multiple applications per PR, map
    deployment environments under [Map environments to
    applications](/configuration/github-deployments#map-environments-to-applications).
    Without GitHub deployments, QA.tech cannot test against PR-specific URLs and
    uses your default environment.
  </Step>

  <Step title="Open a pull request">
    The App reviews pull requests on the mapped repository. How reviews start and what they post is on [GitHub pull request testing](/pr-testing/github#github-app).
  </Step>
</Steps>

## Permissions

The App needs write access to pull requests and statuses so it can post comments, the review, and the **QA.tech / PR Review** check. It only writes when tests run or when the organization is out of credits. The full list of what it posts is on [What the GitHub App posts](/pr-testing/github#what-the-github-app-posts).

## PR Review check on GitHub

The App registers a check run named **QA.tech / PR Review** on pull request commits. You can require it in branch protection. When the check appears for each trigger is on [PR Review check](/pr-testing/github#pr-review-check).

### Integration settings

Configure these under **Settings → Integrations → GitHub App** for the repository:

| Setting | Effect on the PR Review check |
| :- | :- |
| **Auto-run on PRs** | When on, creates the check on PR open/sync (subject to draft rules below). When off, no check on PR open - use `@qa.tech`, the Change Review Action, or the API. |
| **Include draft PRs** | When off (default), draft PRs get a skipped **Draft PR** check instead of an in-progress review. When on, draft PRs are reviewed the same as non-draft PRs (if auto-run is enabled). |
| **Register a commit check** | On by default. When off, QA.tech never posts the **QA.tech / PR Review** check for any trigger (auto-run, `@qa.tech`, the Change Review Action, or the API). Reviews still post the sticky PR comment and appear in the dashboard, but there is no merge gate to require. |
| **PR Triage** | On by default for new projects and new GitHub integrations. Mappings created before that default stay off until you turn them on. When on, automatic reviews skip pull requests that cannot be tested. The check is set to skipped with a **Review skipped** reason, and QA.tech does not comment on the pull request. `@qa.tech` comments and re-runs are never skipped. Use **PR triage prompt** to say which pull requests to skip. [Suggested workflows](/pr-testing/pr-triage) are copy-paste prompts. |

## Code access

Code access is **on by default** for new GitHub App repository mappings. When it is on, chat and PR reviews can clone repositories the GitHub App can access and search source when the knowledge graph or a PR diff is not enough.

If you mapped a repository before this default, turn on **Enable code access** on the same page. You can turn it off at any time.

### Enable or disable code access

<Steps>
  <Step title="Map a GitHub repository">
    Under [**Settings → Integrations → GitHub
    App**](https://app.qa.tech/current-project/settings/integrations?focus=github-app),
    select a repository and click **Save**. New mappings turn **Enable code
    access** on automatically. The toggle appears after the mapping exists.
  </Step>

  <Step title="Adjust Enable code access">
    Use **Enable code access** to turn cloning on or off. The toggle saves
    immediately; you do not need to click **Save** again.
  </Step>
</Steps>

Once enabled:

* Chat and PR reviews clone the mapped repository by default. Sibling repositories the GitHub App installation can access need no extra mapping.
* A scan of the mapped repository starts and adds a **Code gating facts (from repository)** item to **Settings → Knowledge → Library** (auth classes, feature/plan flags, and setup preconditions). Scan status appears under the toggle. Use **Scan** or **Re-scan** to run it again, or **View in library** to open the item.
* Source search is available in the [AI Chat Assistant](/core-concepts/ai-chat-assistant) and during PR reviews.

The GitHub App must have access to each repository you want cloned.

Turn **Enable code access** off to stop cloning. Knowledge items already in the library stay until you remove them.

## Troubleshooting

**PR reviews aren't posting**

* Verify the GitHub App is installed and has access to the repository.
* Check that the repository is selected under **Settings → Integrations → GitHub App**.
* With **PR Triage** on, pull requests that cannot be tested are skipped. The **QA.tech / PR Review** check shows **Review skipped** and the reason. Comment `@qa.tech` to run a review anyway.
* A 403 Forbidden means the App lacks write access to pull requests or statuses. See [Permissions](#permissions).

**Tests run against the wrong URL**

* Map GitHub environments to applications in **Settings → Integrations → GitHub App → Mapped GitHub Environments**. See [Map environments to applications](/configuration/github-deployments#map-environments-to-applications).
* Verify your CI creates GitHub deployment records with `environment_url` set to the preview URL. See [GitHub Deployments](/configuration/github-deployments).
* Check that environment names match between GitHub and QA.tech.

**Chat or reviews cannot search source code**

Turn on **Enable code access** under **Settings → Integrations → GitHub App**. See [Code access](#code-access).

## Related documentation

* **[GitHub pull request testing](/pr-testing/github)** - Start reviews from the App, the Change Review Action, after merge, or for a mobile build
* **[GitHub regression testing](/regression-testing/github)** - Run a test plan from GitHub Actions
* **[GitHub Deployments](/configuration/github-deployments)** - Publish preview URLs from GitHub Actions for automatic PR reviews
* **[AI Chat Assistant](/core-concepts/ai-chat-assistant)** - Source search in chat when code access is enabled
* **[Knowledge](/core-concepts/knowledge)** - Library item created by the code access scan


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.