---
title: "GitLab"
description: "Connect your code with GitLab to enable API Discovery with HawkAI."
url: https://docs.stackhawk.com/integrations/workflows/gitlab/
---

# GitLab

![GitLab](https://docs.stackhawk.com/images/integrations/logos/gitlab.svg)

The StackHawk GitLab integration connects your GitLab group to enable [API Discovery](https://docs.stackhawk.com/platform/api-discovery/) with HawkAI. This integration automatically discovers your organization’s APIs and web applications from connected repositories. It supports GitLab Premium, Ultimate, and self-managed editions with Group Access Tokens enabled.

> **Note:** *This feature is available on the StackHawk [Scale plan](https://www.stackhawk.com/pricing).*

> **Note:** The integration requires a GitLab [Group Access Token](https://docs.gitlab.com/user/group/settings/group_access_tokens/) with permissions to your GitLab repositories (only available on Premium and Ultimate tiers).

## Features

- **Identify Your Testable Assets** Surface all of your testable APIs and web applications, giving you a full picture of your organization’s Attack Surface.
- **Repository Insights** Gain deeper insight into your code through repository details, including identified frameworks and commit activity, so you can prioritize what to test first with StackHawk.
- **Create or Map Applications** Easily create new StackHawk Applications from your discovered repositories, or connect existing Applications to specific repos for consolidated security testing.

## Requirements

**StackHawk:**

- You must have a StackHawk **Scale** plan.
- Ensure you have **Admin** or equivalent permissions to add integrations within StackHawk.

**GitLab:**

- You must have a GitLab license tier that supports [Group Access Tokens](https://docs.gitlab.com/user/group/settings/group_access_tokens/) (e.g., Premium or Ultimate for GitLab SaaS, or a self-managed edition with Group Access Token support).
- If you are on a self-managed GitLab deployment, your instance must be publicly accessible to allow StackHawk’s systems to retrieve repository information. If your instance is behind a firewall or otherwise not reachable over the internet, this integration will not function properly.
- **Note**: For self-managed deployments, we currently don’t support *self-signed certificates*.

## Permissions

1. **GitLab Group Role** The access token must be created with one of the following roles:

- `Owner`
- `Developer`
- `Maintainer`

2. **GitLab Access Token Scope** The Group Access Token must have these scopes enabled:

- `read_repository` - Grants read access (pull) to all repositories within a group.
- `read_api` - Grants read access to the scoped group and related project API.

***Note**: If your organization uses [custom roles](https://docs.gitlab.com/user/custom_roles/), ensure the chosen role has [`read_code` permission](https://docs.gitlab.com/user/custom_roles/abilities/) enabled.*

## Installation

**Create a Group Access Token** Follow GitLab’s documentation on [creating a Group Access Token](https://docs.gitlab.com/user/group/settings/group_access_tokens/):

1. Go to your GitLab Group settings.
2. Navigate to Access Tokens within that group.
3. Click the **Add new token** button.
4. Enter a name (e.g., “StackHawk API Discovery”).
5. Select the role (`Owner`, `Developer`, or `Maintainer`) that meets your organization’s security requirements.
6. Grant the required scopes (`read_repository` and `read_api`).
7. Click **Create Access Token** and securely store it. You will need to provide it to StackHawk.

**StackHawk**

1. Log in to StackHawk and go to the [GitLab Integration page](https://app.stackhawk.com/integrations/gitlab/).
2. Click Connect GitLab.
3. In the pop-up modal:

- Enter your **Group ID** (numeric ID from GitLab).
- Paste your **Group Access Token**.
- *For Self-Managed Instances*: Enter your GitLab Instance URL (e.g., `https://gitlab.example.com`).

4. Click **Connect**. StackHawk will verify your credentials and confirm a successful connection.

## Usage

### Configuration

Configuration takes place on the [API Discovery](https://app.stackhawk.com/attack-surface/) screen in StackHawk. Once your GitLab group is connected, you will see your repositories populate in the Attack Surface. You can then map repositories to either:

- Existing StackHawk Applications, or
- Create new Applications from discovered repos.

### Connecting Multiple GitLab Groups

You may connect multiple GitLab groups through the Integrations screen. Simply click **Connect GitLab** again and provide credentials for the additional group. Each group will appear in a list of configured connections.

### Updating Group Access Token

If your GitLab token expires or needs rotation, you can update it:

1. Navigate to your [GitLab Integration page](https://app.stackhawk.com/integrations/gitlab/) in StackHawk.
2. Click **Manage**.
3. Select **Update** and enter the new Group Access Token.

### Removing the GitLab Integration

To disconnect your GitLab integration from StackHawk:

1. Go to the [GitLab Integration page](https://app.stackhawk.com/integrations/gitlab/) in StackHawk.
2. For each organization you want to remove, click **Manage** then **Disconnect**.
3. Confirm the disconnection by selecting **Yes, Disconnect**.

## Troubleshooting

**Repositories Not Showing Up** There may be a slight delay between connecting your GitLab group and seeing repositories in the Attack Surface, especially if your group contains a large number of repositories. A progress indicator will appear, and repos will populate as the system processes them.

**Network/Access Issues** For self-managed instances, confirm that your GitLab instance is publicly accessible to StackHawk. If it is behind a firewall or VPN without a secured connection path, the integration cannot access the API.

**Insufficient Permissions** Double-check that your Group Access Token has the required role and `read_api` scope.

## Feedback

Have any suggestions, feature requests, or feedback to share? [Contact StackHawk Support](https://docs.stackhawk.com/support/).