oam/knowledge base/gitlab/integrations.md

GitLab integrations

1. Linear
   1. Integration setup
   2. Create MRs that are recognized and automatically linked by Linear
2. Further reading

Linear

Integration setup

Refer Linear's documentation for GitLab integration.

Important

The GitLab installation must be reachable from the Linear servers through the public Internet.

Linear requires an API access token to communicate with the GitLab instance.
The access token is used both to query GitLab's API for information and to post issue linkbacks.

It can be a user's or service account's personal access token, or a project-specific access token.
GitLab doesn't support bot-like accounts, so linkbacks are created under the name of the token's owner. It's recommended to create a new service account for Linear to act as the bot account.

The token needs the api or read_api scope.

Should one select the read_api scope, Linear will not post linkbacks to the issue upon GitLab merge requests.
If using a project access token, that token needs the Reporter role or higher.

Procedure

1. Make sure the GitLab installation is reachable from Linear's servers.
   Their public IPs are currently 35.231.147.226, 35.243.134.228, 34.140.253.14, and 34.38.87.206.

2. [optional but suggested] Create Linear's service account.

3. Create the API access token in one's GitLab instance.

4. Navigate to Linear's Settings > Features > Integrations > GitLab.

5. Click Enable to launch the set-up pop-up.

6. Enter the access token.

7. [if self-hosted] Enter the public GitLab URL without any path.

8. Click Connect.

9. Linear will generate the Webhook URL after it validates the access token.

10. Copy and paste the generated URL to GitLab.
    Do it under:

    • A group's Settings > Webhooks to integrate all projects under it.
    • A project's Settings > Webhooks, to individually connect that specific project.

11. Enable the following triggers for the webhook:

    • Push events.
    • Comments.
    • Merge request events.
    • Pipeline events.

12. Ensure the Enable SSL verification checkbox is checked under SSL verification.

13. Click Save changes.

Create MRs that are recognized and automatically linked by Linear

One does need to follow a bit Linear's documentation for the integration to work.

Note

Some steps seem to be optional, so the automation most likely depends on the MR leveraging one or more of them.

The TL;DR is the following:

1. The GitLab group or project must be configured with Linear's integration's webhook.

2. Create a branch using the format configured in Linear's GitLab integration's settings.

3. Make your changes in that branch, then push it.

4. When creating the MR for the branch:

   • Add the Linear issue's ID to the MR title.
   • Use one or more the magic words Linear requires in the description.
     This works for linking multiple issues.

5. Enjoy the issue's status changing automatically when the MR is closed.

Further reading

• GitLab integration
• GitLab service accounts