> ## 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 GitLab

> Learn how to integrate CodSpeed with GitLab.

## Setup

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

   <Note>
     **Required permissions**: 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](/docs/features/roles-and-permissions) for more
     information.
   </Note>

2. Generate a Personal Access Token on GitLab. CodSpeed accepts fine-grained and
   legacy tokens.

   <Tip>
     **Bot Account**: CodSpeed uses a single user to access GitLab resources on
     behalf of it. You can generate one either for an existing user, or for a new
     dedicated bot account (recommended). This user/account will be the one to
     publish comments on merge requests.
   </Tip>

   <Warning>
     **Permissions**: a token keeps the permissions it was generated with, and
     GitLab offers no way to change them afterwards. Grant everything CodSpeed
     needs before generating the token. To add a permission later, generate a new
     token and save it in your
     [CodSpeed settings](https://app.codspeed.io/settings).
   </Warning>

   <Tabs>
     <Tab title="Fine-grained token">
       Open the
       [fine-grained token form](https://gitlab.com/-/user_settings/personal_access_tokens/granular/new)
       and fill it in:

       * **Expiration date**: set it to one year. It defaults to one month, and your
         CodSpeed integration stops working once the token expires.
       * **Group and project access**: select **All groups and projects that I'm a
         member of**.
       * **Add resource permissions**: grant the permissions below, switching
         between the **Group and project** and **User** tabs of the **Resource
         access** selector.

       On the **Group and project** tab:

       * **CI/CD**: Commit Status (Create), Job (Read).
       * **Project Planning**: Work Item (Create, Delete, Read, Update).
       * **Projects**: Project (Read).
       * **Repository**: Branch (Read), Code (Download, Push), Commit (Read), Merge
         Request (Create, Read, Update), Repository (Read).

       On the **User** tab:

       * **Projects**: Project (Read).
       * **System Access**: Personal Access Token (Read), User (Read).

       For more details about why CodSpeed needs these permissions, check out the
       [GitLab permissions](#gitlab-permissions) section.

       <img src="https://mintcdn.com/codspeed/N0IIqyLAENRpK-OF/assets/create-gitlab-fine-grained-pat.png?fit=max&auto=format&n=N0IIqyLAENRpK-OF&q=85&s=728b10ddaafe4dc8f642057385274457" className="rounded-xl w-full max-w-2xl mx-auto" alt="Create a fine-grained Personal Access Token on GitLab" width="1800" height="3269" data-path="assets/create-gitlab-fine-grained-pat.png" />
     </Tab>

     <Tab title="Legacy token">
       Open the
       [legacy token form](https://gitlab.com/-/user_settings/personal_access_tokens?name=Codspeed+Token\&scopes=api)
       and fill it in:

       * **Expiration date**: set it to one year. It defaults to one month, and your
         CodSpeed integration stops working once the token expires.
       * **Select scopes**: check `api`, which covers everything CodSpeed does.

       <img src="https://mintcdn.com/codspeed/jKaxX6yy-Kzw1C-0/assets/create-gitlab-pat.png?fit=max&auto=format&n=jKaxX6yy-Kzw1C-0&q=85&s=6330166d84b5f4309786070250f9cdc3" className="rounded-xl w-full max-w-lg mx-auto" alt="Create a legacy Personal Access Token on GitLab" width="2493" height="1691" data-path="assets/create-gitlab-pat.png" />

       <Note>
         A group can
         [enforce fine-grained tokens](https://docs.gitlab.com/auth/tokens/fine_grained_access_tokens/#enforce-fine-grained-personal-access-tokens),
         after which legacy tokens stop working on all of its projects.
       </Note>
     </Tab>
   </Tabs>

3. Fill the Personal Access Token in
   [CodSpeed settings](https://app.codspeed.io/settings)

   <Frame>
     <img src="https://mintcdn.com/codspeed/jKaxX6yy-Kzw1C-0/assets/gitlab-pat.png?fit=max&auto=format&n=jKaxX6yy-Kzw1C-0&q=85&s=d8de940190436ca0acfcc757a3f48a89" className="rounded-xl w-full max-w-lg mx-auto" alt="GitLab Personal Access Token section" width="1510" height="634" data-path="assets/gitlab-pat.png" />
   </Frame>

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

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

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

## GitLab permissions

The `api` scope of a legacy token covers everything CodSpeed does. A
fine-grained token grants only the permissions you select, listed here with what
CodSpeed uses them for.

### Group and project

* **CI/CD**
  * **Commit Status (Create)**: required to publish the
    [performance report](/docs/integrations/providers#performance-reports-in-pull-requests)
    as a commit status.
  * **Job (Read)**: required to follow the GitLab CI jobs running your
    benchmarks.
* **Project Planning**
  * **Work Item (Create, Delete, Read, Update)**: required to publish and update
    the performance report comment on merge requests.
* **Projects**
  * **Project (Read)**: required to read repository settings, such as the
    default branch and the visibility.
* **Repository**
  * **Branch (Read)**: required to resolve the head commit of a branch.
  * **Code (Download, Push)**: required to clone a repository and push the
    branch of an optimization opened by the [CodSpeed wizard](/docs/ai/wizard).
  * **Commit (Read)**: required to read commits and the statuses published on
    them.
  * **Merge Request (Create, Read, Update)**: required to read merge requests,
    open the ones the wizard suggests, and request reviewers on them.
  * **Repository (Read)**: required to find the commit two runs have in common,
    which is the baseline a merge request is compared against.

<Note>
  GitLab classifies merge request comments as work item notes, which is why the
  report comment needs the **Work Item** permissions. They also cover issues and
  epics in the same boundary.
</Note>

### User

* **Projects**
  * **Project (Read)**: required to list the repositories you can import.
* **System Access**
  * **Personal Access Token (Read)**: required to read the expiration date and
    the permissions of the token itself.
  * **User (Read)**: required to identify the account CodSpeed acts as when it
    pushes and comments.