GitLab Integration

Goal: Make a GitLab service account that is only for Aisle. Make a Personal Access Token (PAT) for this account. Then enter the PAT into Aisle.

This guide covers GitLab SaaS, GitLab Self-Managed, and GitLab Dedicated. One Aisle connection covers one GitLab instance. To analyze repositories from more instances, do the steps again for each one.

For the GitLab documentation, see GitLab service accounts.

Do the procedure in “Steps”. The sections after the steps give reference data: the token scope, the role, the webhook subscriptions, and problem solutions.

Prerequisites

• You must have access to an Aisle subscription. Your RBAC role must be Admin or CISO. These roles are necessary to add repositories in Aisle.

• You must have a list of the repositories that Aisle will analyze.

• Aisle needs a dedicated account (the service account). The two GitLab service account types (instance and group) are satisfactory. A service account does not use a seat in your GitLab subscription. A PAT of a different type is also satisfactory if it has the necessary access.

• Applicable versions: GitLab SaaS, and GitLab Self-Managed or Dedicated 16.0 or newer. These versions have the REST API v4, which Aisle needs.

• Self-Managed only: do the checks in “Self-Managed GitLab” before the steps.

Necessary operator roles

You, the operator, need a GitLab role with special permissions to make the service account. This is a one-time step.

• gitlab.com: You must be an Owner of a top-level group. GitLab Inc. operates the instance. Thus an instance administrator is not available to you. A service account that a group owns is the only option.

• Self-Managed / Dedicated: You must be an instance Administrator. As an alternative, you can be a top-level group Owner if the setting Allow top-level group owners to create service accounts is on.

Self-Managed GitLab

Before onboarding of a Self-Managed GitLab instance, make sure that these conditions are true:

• The GitLab server version is 16.0 or higher (approximately May 2023). The server has the GitLab REST API v4.

• Your GitLab instance is available from the internet and has a public DNS record.

  • If necessary, Aisle can give you its static IP address.

• The GitLab setting external_url contains the public DNS name of your instance, not an internal name. GitLab makes the web URLs of all projects from this value. Aisle rejects URLs that use internal names (for example, .local names) or names that resolve to private IP addresses.

  • Caution: The external_url value is global. A change has an effect on the URLs in the GitLab UI, the clone URLs, the CI_SERVER_URL value in CI pipelines, and the links in notifications. Git remotes that use the old internal name continue to operate while that name resolves in your internal DNS.

  • After the change, the GitLab-bundled NGINX needs a TLS certificate for the new name (put the certificate in /etc/gitlab/ssl/, or use Let’s Encrypt). If a reverse proxy in front of GitLab does the TLS termination, set nginx['listen_https'] = false and set nginx['listen_port'] to the applicable value.

  • To change the value, edit external_url in /etc/gitlab/gitlab.rb. Then run sudo gitlab-ctl reconfigure. For the full procedure, see Configure the external URL for GitLab.

• Your GitLab instance can send outbound HTTPS traffic to Aisle at https://{customer}.app.aisle.cloud.

• If you have a security proxy, make sure that the proxy does not change the requests or the responses. Inspection of the traffic and addition of HTTP headers cause no problems. There is one exception: the proxy must not intercept the outbound TLS traffic to Aisle and sign it again with an internal CA. This TLS interception stops the webhook delivery, because Aisle makes webhooks with SSL verification on.

• Your GitLab instance uses certificates from public CAs. Do not use self-signed certificates or certificates from internal CAs.

• Make sure that the Git access protocols permit HTTP(S). Go to Admin → Settings → General → Visibility and access controls. The value of “Enabled Git access protocols” must be “Only HTTP(S)” or “Both SSH and HTTP(S)”. Aisle uses only HTTPS.

Steps

1. In GitLab, make a service account. Give it a name such as aisle, aisle-bot, or aisle-service. A clear name identifies the actions of Aisle in an audit. The GitLab activity log will show, for example, commits from “aisle-bot” and not from a personal user account.

2. Add the service account to each project and group that Aisle will analyze. Give the account the Maintainer role.

   • Do not remove the Maintainer role. This role gives permission to push branches, to make merge requests, and to control webhooks at the project level.

   • Aisle automatically makes webhooks on each project that it analyzes. For the events, see “Webhooks”.

   • Add the service account only to the repositories that you will onboard to Aisle.

3. In GitLab, log in as the service account. Select your avatar. Then select Edit profile → Access tokens → Add new token. Make a new PAT with this data:

   1. Token name: Aisle Integration

   2. Expiration date: the end of the PoV engagement, or later

   3. Scope: api. This scope gives full read and write access to the GitLab API, to all groups and projects, and to Git operations through HTTPS. For the list of all scopes, see Personal access token scopes.

   Copy the token immediately. GitLab shows the token only one time.

4. Copy the PAT from GitLab. Then enter the PAT into Aisle:

   1. You can connect your first GitLab organization during the initial Aisle setup. The initial setup needs a connection to a minimum of one repository from an applicable VCS provider.

   2. After onboarding, go to https://{customer}.app.aisle.cloud/app/integrations/vcs. As an alternative, click Integrations → VCS Connections in the left panel.

   3. Click the Add GitLab button. Enter this data:

      • Integration Name: the name of this connection in Aisle, for example gitlab-prod

      • GitLab Server URL: the base URL of your GitLab instance

      • Access Token: the PAT from step 3

      Click Add GitLab. When the credentials are correct, the connection shows “Connected” and the date.

   Note: Enter only the base URL as the GitLab server URL:

   • SaaS: https://gitlab.com

   • Self-Managed: https://something.domain.tld

   • Dedicated: https://tenant_name.gitlab-dedicated.com

5. On the GitLab connection, click Import Repositories. Then select the repositories that Aisle will analyze.

6. We recommend that you enter the context for the imported repositories before you turn on the Analyzer. Enter the context at https://{customer}.app.aisle.cloud/app/custom-context. For more data, see Context in Aisle: how it works and how to use it.

7. In the Repositories section of Aisle, click Enable Analyzer in the row of that repository.

Do a check of the push rules and merge settings

GitLab sets the restrictions for each project. A project can also get restrictions from its group. Open each applicable project. Then examine these settings:

• Settings → Repository → Push Rules

• Settings → Repository → Protected Branches

• Settings → Merge Requests → Approval rules

• Push rules: Push rules can set limits on the commit author emails. They can make signed commits or special commit message formats mandatory. They can also block service accounts. Make sure that the push rules do not block the Aisle service account.

  • If the project makes signed commits mandatory, tell Aisle. Aisle can set commit signing to on for your environment.

  • If the project sets limits on the commit author email domains, make sure that the service account has an email address in a permitted domain.

• Protected branches: Aisle makes branches with the name aisle-fix-{issue-slug}-{fix-id}. The fix ID is the first 8 characters. Make sure that no protected branch pattern matches aisle-fix-*. Such a pattern can prevent a push from the service account.

• Merge request approvals: Mandatory approvals and pipeline checks can prevent the merge of an Aisle merge request after a satisfactory push. Make sure that the Aisle merge requests can obey these checks. If they cannot, prepare a manual override.

• Commit email: Aisle makes commits as the service account from step 1. Aisle uses the email of that account. If an email is not available, Aisle uses aisle@aisle.com.

• Merge request base branch: Aisle makes a feature branch, for example aisle-fix-{issue-slug}-{fix-id}, from the branch that you set for the repository in Aisle. The initial value is the default branch of the project. Aisle applies the fix and pushes the feature branch. Then Aisle opens a merge request into the set branch.

Reference

These sections give the details for the steps: the token scope, the role, and the webhook subscriptions. You do not need to read them in order.

Token scope and role

The PAT needs the api scope. This scope gives read and write access to the GitLab API, to the groups and projects, and to Git operations through HTTPS. Aisle examines the scope when you connect. Aisle rejects a token without the api scope immediately.

The service account needs the Maintainer role on each project. This role gives permission to push branches, to make merge requests, and to control webhooks at the project level. Aisle does not examine the role when you connect. A missing role shows as an error when Aisle first does the related operation.

The operations that Aisle does in GitLab

• Read: Aisle reads the repository contents, the branches, the merge requests, and the pipeline statuses.

• Monitor: Aisle makes a webhook on each imported project. The webhook sends events to Aisle (see “Webhooks”).

• Write: Aisle makes merge requests, comments on merge requests, and commit statuses.

• Push: Aisle pushes only to its own aisle-fix-* branches. Aisle does not push to your default branch or to protected branches. Each fix comes as a merge request.

Webhooks

Aisle makes the webhooks at the project level, with the name “Aisle”. Aisle makes them with SSL verification on. Aisle controls and repairs its webhooks automatically.

Replace the PAT

GitLab sets a maximum lifetime for tokens. The standard limit is 365 days. Replace the PAT before the expiration date:

1. In GitLab, log in as the service account. Make a new PAT with the same data as in step 3.

2. In Aisle, go to Integrations → VCS Connections.

3. On the GitLab connection, open the menu. Then select Update Connection.

4. Enter the new PAT in the Access Token field. Then click Save.

5. In GitLab, revoke the old token.

Troubleshooting

Off-boarding

When you disconnect Aisle, revoke the PAT:

1. In Aisle, remove the connected repositories or the full GitLab integration first. Aisle then deletes its webhooks while the PAT is serviceable. If you revoke the PAT first, the Aisle webhooks stay on the projects. You must then remove the webhooks manually in the project Settings → Webhooks.

2. In GitLab, go to Edit profile → Access tokens for the service account.

3. Find the Aisle Integration token. Then select Revoke.

For the full procedure, see Revoke a personal access token.

You can deactivate the service account as an alternative to deletion. A deactivated account keeps a clear identity in the audit history.