Gitlab

The StackHawk GitLab integration lets you connect your code via your GitLab group to unlock API Discovery with HawkAI. Whether you’re using GitLab Premium, Ultimate, or a self-managed edition (with Group Access Tokens enabled and publicly accessible), this integration automates discovery of your organization’s APIs and web applications for continuous security testing.

This feature is available on the StackHawk Enterprise plan.

The integration requires a Gitlab Group Access Token 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 Enterprise 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 (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
   • Reporter
   • Developer
   • Maintainer
2. GitLab Access Token Scope
   The Group Access Token must have at least one of these scopes enabled:
   • read_api - Grants read access to the group and related project APIs.

Note: If your organization uses custom roles, ensure the chosen role has read_code permission enabled.

Installation

Create a Group Access Token
Follow GitLab’s documentation on creating a Group Access Token:

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, Reporter, Developer, or Maintainer) that meets your organization’s security requirements.
6. Grant one of the required scopes (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.
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 Host & Port (e.g., https://gitlab.example.com:8675309).
4. Click Connect. StackHawk will verify your credentials and confirm a successful connection.

Usage

Configuration

Configuration takes place on the API Discovery 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 Personal Access Token

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

1. Navigate to your GitLab Integration page 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 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 .