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

# GitLab

> Connect GitLab to let ewake correlate production issues with merge requests, deployments, and infrastructure code changes.

<Info>
  **What you'll get:** After connecting GitLab, ewake can correlate production issues with recent merge requests and deployments, surface the diff that likely caused a regression, and analyse infrastructure-as-code changes (Terraform, Kubernetes manifests) alongside application code.
</Info>

***

## Prerequisites

* **Owner** access to your top-level GitLab group (GitLab.com) or **administrator** access (self-managed), required to create a service account
* Access to your ewake dashboard

<Note>
  Connect ewake with a **dedicated service account** rather than a personal access token. A service account isn't tied to an individual, so access survives staff changes, stays least-privilege and auditable, and won't break when someone leaves or rotates their own tokens. This is GitLab's recommended pattern for integrations.
</Note>

***

## Configuration

Follow the steps for your GitLab deployment.

<Tabs>
  <Tab title="GitLab.com (SaaS)">
    <Steps>
      <Step title="Create a service account">
        As a top-level group **Owner**, use **Search or go to** to open your group, then go to **Settings → Service accounts** → click **Add service account**.

        Enter a name (e.g. `ewake`) and click **Create service account**.
      </Step>

      <Step title="Create an access token for the service account">
        On the **Settings → Service accounts** page, find the service account, open the **⋮** (vertical ellipsis) menu → **Manage access tokens** → **Add new token**.

        Select the following scopes:

        | Scope             | Why                                                           |
        | ----------------- | ------------------------------------------------------------- |
        | `read_api`        | Read project data, merge requests, pipelines, and deployments |
        | `read_repository` | Read source code and diffs                                    |

        Set an expiry date and click **Create personal access token**.

        <Note>
          Copy the token now, GitLab will not show it again after you leave this page.
        </Note>
      </Step>

      <Step title="Give the service account access to your projects">
        Add the service account as a member of each group or project you want ewake to monitor (**Manage → Members → Invite members**) with the **Reporter** role.

        <Note>
          A token with no project membership reads nothing. **Reporter** is the minimum role required to read code, merge requests, and pipelines on private projects, and adding the service account at the **group** level covers every project inside that group.
        </Note>
      </Step>

      <Step title="Connect in ewake">
        In your ewake dashboard, go to **Integrations → GitLab** → click **Configure**.

        | Field                     | Value                                       |
        | ------------------------- | ------------------------------------------- |
        | **GitLab Base URL**       | `https://gitlab.com`                        |
        | **Personal Access Token** | The service account token created in Step 2 |

        Click **Test Configuration**, then **Save**.
      </Step>

      <Step title="Select projects">
        Choose which GitLab projects ewake should monitor.

        <Note>
          We recommend including all projects with production services. Infrastructure repos (Terraform, Kubernetes configs) are particularly valuable for ewake's root-cause analysis.
        </Note>

        <Check>
          GitLab is connected. Ewake can now correlate incidents with merge requests and deployments.
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Self-managed">
    <Steps>
      <Step title="Create a service account">
        <Note>
          Service accounts require GitLab **Enterprise Edition** — the open-source **Community Edition (CE)** cannot create them, so you won't see **Settings → Service accounts** on a CE instance. (On EE Free tier, service accounts are available from GitLab 18.11.)
        </Note>

        As an **administrator**, select **Admin** (top right), then go to **Settings → Service accounts** → click **Add service account**.

        Enter a name (e.g. `ewake`) and click **Create service account**.
      </Step>

      <Step title="Create an access token for the service account">
        On the **Settings → Service accounts** page, find the service account, open the **⋮** (vertical ellipsis) menu → **Manage access tokens** → **Add new token**.

        Select the following scopes:

        | Scope             | Why                                                           |
        | ----------------- | ------------------------------------------------------------- |
        | `read_api`        | Read project data, merge requests, pipelines, and deployments |
        | `read_repository` | Read source code and diffs                                    |

        Set an expiry date and click **Create personal access token**.

        <Note>
          Copy the token now, GitLab will not show it again after you leave this page.
        </Note>
      </Step>

      <Step title="Give the service account access to your projects">
        Add the service account as a member of each group or project you want ewake to monitor (**Manage → Members → Invite members**) with the **Reporter** role.

        <Note>
          A token with no project membership reads nothing. **Reporter** is the minimum role required to read code, merge requests, and pipelines on private projects, and adding the service account at the **group** level covers every project inside that group.
        </Note>
      </Step>

      <Step title="Connect in ewake">
        In your ewake dashboard, go to **Integrations → GitLab** → click **Configure**.

        | Field                     | Value                                                               |
        | ------------------------- | ------------------------------------------------------------------- |
        | **GitLab Base URL**       | Your self-hosted GitLab URL (e.g. `https://gitlab.your-domain.com`) |
        | **Personal Access Token** | The service account token created in Step 2                         |

        Click **Test Configuration**, then **Save**.
      </Step>

      <Step title="Select projects">
        Choose which GitLab projects ewake should monitor.

        <Note>
          We recommend including all projects with production services. Infrastructure repos (Terraform, Kubernetes configs) are particularly valuable for ewake's root-cause analysis.
        </Note>

        <Check>
          GitLab is connected. Ewake can now correlate incidents with merge requests and deployments.
        </Check>
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

<Note>
  Ewake uses **read-only** access to GitLab. It never pushes commits, creates branches, or comments on merge requests.
</Note>

<CardGroup cols={2}>
  <Card title="Track deployments from GitLab CI/CD →" icon="rocket" href="/integrations/deployment/deployment-tracking">
    Send deployment events to ewake directly from your CI/CD pipeline.
  </Card>

  <Card title="What does ewake access in GitLab? →" icon="shield-halved" href="/security/permissions#gitlab">
    Full read-only permission breakdown for the GitLab integration.
  </Card>
</CardGroup>