GitLab

Overview

Heeler connects to GitLab at the group level and uses a GitLab Group Hook to automate assessment of code and dependencies. To do so, Heeler requires:

• GitLab Group with project repositories you want Heeler to analyze

• Group Access Token with required role and scopes for Heeler to perform assessments

• Group Hook with Heeler Installation Token to push information to Heeler for assessment

Update or Create Gitlab Group

By connecting at the group level, Heeler can analyze all project repositories that are members of that group. Therefore, the scope of Heeler's analysis can be maintained simply by adding or removing repositories from the Group. If an appropriate Group in Gitlab exists, then proceed to the next step.

If there is no appropriate Group, then navigate to Groups and select Create Group. It should look like something like this below.

Add desired groups and/or individual projects to the Group. To reduce maintenance, use group templates or automation to automatically curate new projects into the Group.

Create Group Access Token

Heeler uses a Group Access Token to authenticate with your Group and to define its permissions. To create the token, use the navigation bar on the left hand side, select Settings at the bottom and then Access tokens.

The permissions required by Heeler are:

• Role: Reporter

• Scopes:

  • read_api : Required for Heeler to gather information about the project repositories in your Group

  • read_repository : Required for Heeler to correlate project repositories to Heeler Services and to run security analysis

Add Gitlab to Heeler

1. In Heeler, select the Settings icon from the top navigation
2. Select Connections -> Code Organizations then select Add Code Organization

1. Enter an Organization Name for the Gitlab Group. It does not need to match the name of the group in Gitlab

2. Enter the Access Token

3. Select the appropriate option for Server

   1. SaaS: Gitlab Group is accessible via gitlab.com. Heeler will validate the Access Token and harvest information about the Gitlab Group and all Group members

   2. On-Prem: Heeler will require the deployment of an on-prem Broker to facilitate communication between your Gitlab Group and Heeler. Enter the URL that the Broker will use to connect to your on-prem Gitlab Group

4. Select Save

1. After saving, the modal will update with an Installation Token. You will use the token to allow a Gitlab Group Hook to push information to Heeler

Create Gitlab Group Hook

Creating the Gitlab Group Hook enables your Gitlab Group to send commit and merge request notifications and information to Heeler, either directly through the public Heeler endpoint or via a Broker deployed to your on-prem environment.

1. In Gitlab, return to your Group and navigate to Webhooks in the Settings menu (it is directly above Access tokens as shown under Create Group Access Token)

2. Create a web hook

3. URL

   1. SaaS: Enter the public Heeler endpoint for web hooks (This needs to be documented)

   2. On-Prem: Enter the Broker endpoint for web hooks. The Broker endpoint is its URL followed by the path /api/v1/gitlab/payload. For example, if the Broker URL is http://heeler-broker.acme-internal.com, then the Broker endpoint is http://heeler-broker.acme-internal.com/api/v1/gitlab/payload.

4. Secret token. Enter the Installation Token

5. Trigger

   1. Push events: Check

      1. All branches: Check

6. Enable SSL verification: Check. (N.b., the option is not shown on the screenshot due to space limitations)