Skip to main content

GitLab

Overview​

Connect GitLab to StackGuardian to source Infrastructure as Code (IaC) and Policy code from your repositories and trigger Workflow runs automatically on pull requests, pushes, or tag creation.

To integrate GitLab with StackGuardian:

  1. Create a GitLab token. You have three options:
  2. Once the token is created, configure the connector in StackGuardian.

Create a personal access token​

This method grants StackGuardian access to your GitLab account and all accessible projects. Follow these steps to create a personal access token:

  1. Log in to GitLab.
  2. Click on your avatar and select Edit profile.
  3. Go to Access Tokens in the sidebar.
  4. Click Add New Token.
  5. Provide a name for the token.
  6. Optionally, set an expiry date (default is 365 days).
  7. Select the api scope.
  8. Click Create Personal Access Token.
  9. Copy and store the token securely. It will not be shown again.
GitLab token creation

GitLab token creation

Create a group access token​

This method limits StackGuardian's access to a specific GitLab group and its projects. Follow these steps to create a group access token:

  1. Log in to GitLab.
  2. Open the desired group.
  3. Go to Settings > Access Tokens.
  4. Click Add new token.
  5. Enter a token name.
  6. Set an expiry date (up to 365 days).
  7. Choose a role: Reporter or higher.
  8. Select scopes:
    • read_repository: Allows reading the repository.
    • api: Permits API access that includes various read and write actions.
  9. Click Create group access token.
  10. Save the token securely. It won't be shown again.
note

Handle the Group Access Token with care, as it grants access to all projects within the group.

Create a project access token​

This method limits StackGuardian’s access to a specific GitLab project. Follow these steps to create a project access token:

  1. Log in to GitLab.
  2. Open the desired project.
  3. Go to Settings > Access Tokens.
  4. Click Add new token.
  5. Enter a token name.
  6. Set an expiry date (up to 365 days).
  7. Choose a role: Reporter or higher.
  8. Select scopes:
    • read_repository: Allows reading the repository.
    • api: Permits API access that includes various read and write actions.
  9. Click Create project access token.
  10. Save the token securely. It won't be shown again.
note

Handle the Project Access Token with care, as it grants repository access.

Project Access Token

Project access token

Configure the connector in StackGuardian​

Once you have the token, follow these steps:

  1. In StackGuardian, navigate to Organization Settings → Connectors → Version control providers.
  2. Select + Connect with VCS provider.
  3. In the Connect with VCP modal, select GitLab as the version control provider.
  4. Select your hosting type:
  5. Choose an authentication method:

GitLab.com​

Use this hosting type if your repositories are hosted on gitlab.com.

No additional configuration is required — select your authentication method and proceed directly to the credentials section.

Personal access token​

  1. Enter a Connector name. The connector ID is auto-generated from the name.

  2. Under Credentials, fill in the following:

    FieldDescription
    User nameYour GitLab username, for example john.doe
    Access tokenA personal access token generated in GitLab

  3. Select Create to finalize the connector.

Connect with VCP modal showing GitLab.com selected with Personal access token and the User name and Access token credential fields

Connect with Personal access token

Group access token​

  1. Enter a Connector name. The connector ID is auto-generated from the name.
  2. Under Credentials, enter the Access token generated for your GitLab group.
  3. Select Create to finalize the connector.
Group access token

Group access token

Project access token​

  1. Enter a Connector name. The connector ID is auto-generated from the name.
  2. Under Credentials, enter the Access token generated for your GitLab project.
  3. Select Create to finalize the connector.
Connect with VCP modal showing GitLab.com selected with Project access token and the Access token credential field

Connect with Project access token

Self-managed​

Use this hosting type if your GitLab instance is hosted on your own infrastructure.

In addition to selecting an authentication method, you must provide the URLs for your GitLab instance under Configuration:

FieldDescription
HTTP URLYour GitLab instance URL, for example https://gitlab.yourcompany.com
API URLYour GitLab API endpoint, for example https://gitlab.yourcompany.com/api/v4

Do not include a trailing slash in either URL.

Connect with VCP modal showing Self-managed selected with empty HTTP URL and API URL configuration fields

Connect with Self-managed

Once you have filled in the Configuration fields, follow the same steps as the corresponding authentication method under GitLab.com above.

Dedicated​

Use this hosting type if your GitLab instance is hosted on a GitLab-managed dedicated environment.

The HTTP URL and API URL fields are pre-filled with the default GitLab endpoints. Update these values if your dedicated instance uses custom URLs.

FieldDefault value
HTTP URLhttps://gitlab.com
API URLhttps://gitlab.com/api/v4

Do not include a trailing slash in either URL.

Connect with VCP modal showing Dedicated selected with HTTP URL and API URL pre-filled with GitLab default values

Connect with Dedicated selected

Once you have confirmed the Configuration fields, follow the same steps as the corresponding authentication method under GitLab.com above.