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

# Integrating with GitHub

> Learn how to integrate CodSpeed with a GitHub repository.

## Setup

1. Go to your [CodSpeed settings](https://app.codspeed.io/settings)

   <Note>
     If you are importing a repository from an organization, you need to be either
     a **Provider Admin** or a **Admin** of this organization. Check out the
     [CodSpeed Roles & Permissions page](/features/roles-and-permissions) for more
     information.
   </Note>

2. Click the "Import" button:

   <Frame>
     <img src="https://mintcdn.com/codspeed/jKaxX6yy-Kzw1C-0/assets/add-new-repository.png?fit=max&auto=format&n=jKaxX6yy-Kzw1C-0&q=85&s=84fb767d81b990e9ba590bf2a8adc0c8" className="rounded-xl w-full max-w-lg mx-auto" alt="Adding a new repository from the settings page" width="1380" height="864" data-path="assets/add-new-repository.png" />
   </Frame>

3. Select the organization or the user you want to import the repository from:

   <img src="https://mintcdn.com/codspeed/jKaxX6yy-Kzw1C-0/assets/select-organization.png?fit=max&auto=format&n=jKaxX6yy-Kzw1C-0&q=85&s=04ad62074c1d5b91f6f90748cf3067f2" className="rounded-xl w-full max-w-sm mx-auto" alt="Github App organization selection" width="1232" height="906" data-path="assets/select-organization.png" />

4. Select the repositories you want to benchmark and click on "Install"

5. Your repositories should appear in the list of repositories.

   <Frame>
     <img src="https://mintcdn.com/codspeed/SwdNrtJu0iSVsYr5/assets/github-connect-repo.png?fit=max&auto=format&n=SwdNrtJu0iSVsYr5&q=85&s=291bd83ddc1141ab0d49028e4b4da39c" alt="Repositories list after installation" className="rounded-xl w-full max-w-md mx-auto" width="4074" height="1672" data-path="assets/github-connect-repo.png" />
   </Frame>

You can now continue and [setup the continuous reporting](/integrations/ci).

## GitHub Permissions

CodSpeed requires the following permissions to work properly with GitHub:

### Account permissions

* **Email addresses (Read-only)**: required to notify users about installation
  and configuration changes.

<Info>
  **Act on your behalf**

  When you connect CodSpeed to your GitHub account, you might see a message saying
  the app wants to “Act on your behalf.” This message is a display inconsistency
  on GitHub's side and doesn't reflect what CodSpeed can actually do.

  <img src="https://mintcdn.com/codspeed/Dt-_mEYL876ID0AT/assets/github-act-on-your-behalf.png?fit=max&auto=format&n=Dt-_mEYL876ID0AT&q=85&s=068da8abf117de45feb9afc30dd758e7" className="rounded-xl w-full max-w-sm mx-auto" alt="GitHub Authorization Request" width="1344" height="1122" data-path="assets/github-act-on-your-behalf.png" />

  The only permission CodSpeed requires from your personal GitHub account is read
  access to your email address, which allows us to identify your account and
  contact you if needed.

  All interactions will otherwise be performed through the CodSpeed GitHub App,
  which is installed on repositories you authorize but anyway, CodSpeed can
  **never** perform actions on your behalf. For more technical background, see
  [this GitHub discussion](https://github.com/orgs/community/discussions/37117).
</Info>

### Repository Permissions

* **Actions (Read/Write)**: required to access the execution logs of the
  workflow runs and to annotate/cancel CodSpeed workflows.

* **Checks (Read/Write)**: required to create check runs for the
  [performance reports](/integrations/providers#performance-reports-in-pull-requests).

* **Commit statuses (Read-only)**: required to access commit status checks.

* **Contents (Read/Write)**:
  * Read access: required to access branches and commits.
  * Write access: required to recommend performance improvements by pushing
    commits to a dedicated branch.

    <Info>
      This permission does not bypass any branch protection rules you have set
      up on your repository
    </Info>

* **Pull requests (Read/Write)**: required to access pull requests and annotate
  them with
  [performance reports](/integrations/providers#performance-reports-in-pull-requests)
  comments.

* **Issues (Read/Write)**: required to access issues and respond to pull request
  comments mentioning [@codspeedbot](/ai/wizard).

* **Metadata (Read-only)**: mandatory for all GitHub Apps.

* **Workflows (Write)**: required to [automate CodSpeed setup](/ai/wizard) on
  repositories.

### Organization permissions

* **Members (Read-only)**: required to access the list of members of the
  organization.

* **Self-hosted runners (Read/Write)**: required to register
  [CodSpeed Macro runners](/instruments/walltime) at the organization level.

<Info>
  If you have any concerns about the permissions we require, please
  [contact us](mailto:support@codspeed.io).
</Info>