👋 Email us at [email protected] with questions or feedback. We'd love to hear from you. If you have an account with RWX, view your support page for access to support via Slack.

🚧 DISCLAIMER 🚧

Integrating with GitLab is not yet enabled.

Overview

Captain's integrations enable a large portion of its functionality. This document details how to configure GitLab to integrate with Captain and outlines some GitLab-specific concepts related to the process.

Connecting GitLab to Captain

  1. Navigate to your organization's integrations settings page. Then, click "+ GitLab".
  2. Enter your access token.
  3. If you're using a self-managed instance of GitLab, enter your host name in the "Instance" field (gitlab.com is prefilled for GitLab SaaS users).
  4. Click "Complete".
  5. Copy the generated webhook secret -- you'll need it in the next step.
  6. Create one or more GitLab webhooks which send "Merge request events" to the Incoming Webhook URL displayed in Captain. Use the secret you saved in the last step.
  7. Done! Captain is now integrated with GitLab.

Access Tokens

GitLab provides three kinds of access tokens: Group, Project, and Personal.

Group access tokens provide access to the projects within that group and are the easiest way to integrate with Captain. A single access token can set up Captain for all of your projects. With a group access token, you only need to create one Captain integration per GitLab group (if you have multiple groups, you can integrate more than once).

Project Access Tokens

Project access tokens provide access to the single project for which it was generated. A project access token scopes Captain's visibility further to provide you fine-grained control over which projects Captain will know about. To add multiple projects to Captain, though, you'll need to integrate multiple times (we only support one access token per integration).

In case you don't have a Premium or higher subscription to GitLab, personal access tokens provide access to every group and project accessible to the user who generated it. We recommend avoiding this if possible, because the integration will break if that user loses access. If necessary, consider creating a service account and restricting its access.

Webhooks

GitLab provides two kinds of webhooks: Group and Project.

Group webhooks provide webhook notifications for the projects within that group and are the easiest way to integrate with Captain. A single webhook can be configured and set up Captain for all of your Projects.

Project Webhooks

Project webhooks provide webhook notifications for the single project for which it was configured. Like project access tokens, a project webhook scopes Captain's visibility further to provide you fine-grained control over which projects Captain will know about. If used in conjunction with a group access token, you can configure multiple project webhooks with the same webhook secret from a single Captain integration (or you can create additional webhook secrets). If used in conjunction with a project access token, again you'll need to integrate multiple times (we only support one access token per integration).

Rotating a webhook secret

  1. Navigate to your organization's integrations settings page.
  2. Click the GitLab integration with the secret you'd like to rotate.
  3. Click "Create new" next to the "Webhook Secrets" heading.
  4. Copy the generated webhook secret and store it in a safe, secure place.
  5. Swap any webhooks using the old secret to the new one.
  6. (optional) Leave the old token active for a few days to verify nothing is using it (Captain shows when it was last used).
  7. Revoke the old secret.