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

# Connect GitHub or GitLab for Deployment Tracking

> Link your GitHub or GitLab repositories so deployment events and pipeline failures flow directly into Scrubbe as signals and incident tickets.

Connecting GitHub or GitLab gives Scrubbe visibility into your deployments and pipelines. When a deployment fails or a pipeline job breaks, Scrubbe ingests the event and correlates it with active incidents using the commit SHA and deployment metadata. You need the `ENGINEER` role or higher to connect either integration.

<Tabs>
  <Tab title="GitHub">
    ## Connect GitHub

    <Steps>
      <Step title="Initiate the OAuth flow">
        Send an authenticated request to the GitHub connect endpoint. Scrubbe returns a GitHub OAuth authorization URL.

        ```http theme={null}
        POST /api/v1/integrations/github/connect
        Authorization: Bearer <your-access-token>
        ```

        **Response:**

        ```json theme={null}
        {
          "success": true,
          "message": "GitHub OAuth URL generated",
          "data": {
            "url": "https://github.com/login/oauth/authorize?client_id=..."
          }
        }
        ```
      </Step>

      <Step title="Authorize in GitHub">
        Open the returned `url` in your browser. GitHub will ask you to authorize Scrubbe to access your repositories. After you click **Authorize**, GitHub redirects to the Scrubbe callback endpoint automatically.
      </Step>

      <Step title="Scrubbe completes the connection">
        Scrubbe handles the OAuth callback at:

        ```
        GET /api/v1/integrations/github/callbacks/github
        ```

        You do not need to call this endpoint directly. After the callback succeeds, your GitHub account is linked and Scrubbe can access your repositories.
      </Step>

      <Step title="List and save repositories">
        Fetch the repositories available on your connected GitHub account:

        ```http theme={null}
        GET /api/v1/integrations/github/repos
        Authorization: Bearer <your-access-token>
        ```

        Then save the repositories you want Scrubbe to monitor:

        ```http theme={null}
        PATCH /api/v1/integrations/github/repos
        Authorization: Bearer <your-access-token>
        Content-Type: application/json

        {
          "repos": ["your-org/api-service", "your-org/frontend"]
        }
        ```
      </Step>

      <Step title="Register the webhook in GitHub">
        In your GitHub repository settings, add a webhook pointing to the Scrubbe ingestion endpoint:

        * **Payload URL:** `https://your-scrubbe-instance/api/v1/ingestion/github`
        * **Content type:** `application/json`
        * **Events:** Select **Workflow runs** and **Deployment statuses**
        * **Secret:** Use your Scrubbe API key as the webhook secret

        Scrubbe also exposes a lower-level integration webhook at `POST /api/v1/integrations/github/webhook` which handles signature-verified push and deployment events at the integration layer.
      </Step>
    </Steps>

    ## How GitHub events map to incidents

    When a `deployment_status` event with a `failure` state arrives, Scrubbe creates or updates an incident ticket with:

    * The commit SHA from the deployment payload
    * The repository and environment name
    * A severity of `ERROR` or `CRITICAL` depending on the failure type

    When a `workflow_run` event with a `failure` conclusion arrives, Scrubbe records a `BUILD_FAILED` signal and links it to any open incident for the same service and environment.
  </Tab>

  <Tab title="GitLab">
    ## Connect GitLab

    <Steps>
      <Step title="Initiate the OAuth flow">
        Send an authenticated request to the GitLab connect endpoint. Scrubbe returns a GitLab OAuth authorization URL.

        ```http theme={null}
        POST /api/v1/integrations/gitlab/connect
        Authorization: Bearer <your-access-token>
        ```

        **Response:**

        ```json theme={null}
        {
          "success": true,
          "message": "GitLab OAuth URL generated",
          "data": {
            "url": "https://gitlab.com/oauth/authorize?client_id=..."
          }
        }
        ```
      </Step>

      <Step title="Authorize in GitLab">
        Open the returned `url` in your browser. GitLab will ask you to authorize Scrubbe to read your projects and receive pipeline events. After you click **Authorize**, GitLab redirects to the Scrubbe callback endpoint automatically.
      </Step>

      <Step title="Scrubbe completes the connection">
        Scrubbe handles the OAuth callback at:

        ```
        GET /api/v1/integrations/gitlab/callback
        ```

        You do not need to call this endpoint directly. After the callback succeeds, your GitLab account is linked.
      </Step>

      <Step title="List and save projects">
        Fetch the projects available on your connected GitLab account:

        ```http theme={null}
        GET /api/v1/integrations/gitlab/projects
        Authorization: Bearer <your-access-token>
        ```

        Then save the projects you want Scrubbe to monitor:

        ```http theme={null}
        PATCH /api/v1/integrations/gitlab/projects
        Authorization: Bearer <your-access-token>
        Content-Type: application/json

        {
          "projects": ["your-group/api-service", "your-group/frontend"]
        }
        ```
      </Step>

      <Step title="Register the webhook in GitLab">
        In your GitLab project settings under **Webhooks**, add a webhook pointing to the Scrubbe ingestion endpoint:

        * **URL:** `https://your-scrubbe-instance/api/v1/ingestion/gitlab`
        * **Secret token:** Your Scrubbe API key
        * **Trigger:** Select **Pipeline events** and **Deployment events**

        Scrubbe also exposes an integration-layer webhook at `POST /api/v1/integrations/gitlab/webhook` for signature-verified event delivery.
      </Step>
    </Steps>

    ## How GitLab events map to incidents

    When a pipeline event with a `failed` status arrives, Scrubbe creates or updates an incident ticket with:

    * The commit SHA (`sha`) from the pipeline payload
    * The project path and environment
    * A `BUILD_FAILED` or `DEPLOYMENT_FAILED` event type depending on the pipeline stage

    Scrubbe deduplicates events automatically using the commit SHA and environment, so a flapping pipeline does not create duplicate incidents.
  </Tab>
</Tabs>

## Deployment correlation

Regardless of whether you use GitHub or GitLab, Scrubbe links deployment signals to open incident tickets by matching the service name and environment. When a deployment failure arrives for a service that already has an open incident, Scrubbe attaches the deployment metadata to that ticket rather than opening a new one. You can view the linked deployment details in the incident's **Changes** panel.

<Note>
  You can also initiate the OAuth flow with a `GET` request to `/api/v1/integrations/github/connect` or `/api/v1/integrations/gitlab/connect` if you prefer to navigate directly from a browser.
</Note>