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

# How to integrate with GitLab

> Connect QA Wolf to GitLab CI/CD to automatically trigger test runs when you deploy code from your repository.

If your repositories are hosted on GitLab.com or on a GitLab Enterprise Server instance with internet access, this is the recommended setup. The integration connects directly to your QA Wolf environments.

<Tip>
  If your GitLab instance does not allow outbound HTTPS connections (for example, an air-gapped GitLab Enterprise installation), use the QA Wolf CI SDK instead.
</Tip>

<Check>
  Make sure you have:

  * Admin or Maintainer access to the GitLab project.
  * Access to your QA Wolf workspace.
  * At least one QA Wolf environment already configured.
  * A QA Wolf API key.
</Check>

## Enable the GitLab integration in QA Wolf

<Steps>
  <Step>
    Open the `Workspace name` dropdown in QA Wolf and click **Workspace Settings**.
  </Step>

  <Step>
    Click **Integrations**, then click **Enable** next to **GitLab**. This opens GitLab, where you'll be prompted to sign in if you have not already done so. Follow the prompts to connect your GitLab account or group.

    <Frame>
      <img src="https://mintcdn.com/qawolf/4XZ5s3xcaUDfoNRS/images/integrating-with-CI-CD/image-10.png?fit=max&auto=format&n=4XZ5s3xcaUDfoNRS&q=85&s=209efa3c17f442318df554c5aad87287" alt="" width="2016" height="1612" data-path="images/integrating-with-CI-CD/image-10.png" />
    </Frame>

    You'll be asked to provide a **Group Access Token** with the **Maintainer** role and **API** scope.

    <Danger>
      The Maintainer role is required because Developer tokens cannot create pipeline checks on protected branches.
    </Danger>

    Once connected, QA Wolf can set commit statuses and link test runs to GitLab commits.
  </Step>
</Steps>

### Find the QAWOLF\_API\_KEY

<Steps>
  <Step>
    Open the `Workspace name` dropdown in QA Wolf and click **Workspace Settings**.
  </Step>

  <Step>
    Choose **Integrations** and then click the <Icon icon="clipboard" /> icon to the right of **API Key** under **API Access**.

    <Frame>
      <img src="https://mintcdn.com/qawolf/4XZ5s3xcaUDfoNRS/images/integrating-with-CI-CD/image-12.png?fit=max&auto=format&n=4XZ5s3xcaUDfoNRS&q=85&s=9b6effe7fc081de3debec55049273a90" alt="" width="2016" height="1612" data-path="images/integrating-with-CI-CD/image-12.png" />
    </Frame>
  </Step>
</Steps>

### Add the QAWOLF\_API\_KEY secret

<Steps>
  <Step>
    Open your GitLab project.
  </Step>

  <Step>
    Go to **Settings → CI/CD → Variables**.
  </Step>

  <Step>
    Click **Add variable**.
  </Step>

  <Step>
    Name the variable `QAWOLF_API_KEY`, paste your API key, and save.
  </Step>
</Steps>

You can also define additional variables, such as a deployment URL, if your pipeline uses them.

## Add the deploy notification to GitLab CI/CD

QA Wolf provides a public API endpoint that your GitLab pipeline can call upon successful deployment. Add a job to your `.gitlab-ci.yml` that runs after your deploy step completes successfully.

```yml expandable theme={null}
stages:
  - build
  - deploy
  - notify

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: staging

notify_qawolf:
  stage: notify
  script:
    - |
      curl -X POST "https://app.qawolf.com/api/webhooks/deploy_success" \
        -H "Authorization: Bearer $QAWOLF_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{
          \"branch\": \"$CI_COMMIT_REF_NAME\",
          \"deployment_type\": \"staging\",
          \"deployment_url\": \"$QA_WOLF_DEPLOY_URL\",
          \"sha\": \"$CI_COMMIT_SHA\",
          \"hosting_service\": \"GitLab\"
        }"
  when: on_success
  needs: ["deploy"]
```

This job tells QA Wolf that a new deployment is ready for testing.

<Steps>
  <Step>
    Run your GitLab CI/CD pipeline to trigger a deployment.
  </Step>

  <Step>
    Wait for the pipeline to complete successfully.
  </Step>

  <Step>
    Open QA Wolf and confirm a new run appears under the expected environment.
  </Step>
</Steps>

## Verify the integration

<Steps>
  <Step>
    Push a new commit to your main branch and wait for your deployment to complete.
  </Step>

  <Step>
    Open QA Wolf and confirm a new run appears under the expected environment.
  </Step>
</Steps>

## Related

* [webhooks/deploy\_success](/qawolf/deploy-success)
* [REST API](/qawolf/rest-overview)