oam/knowledge base/gitlab/integrations.md

GitLab integrations

1. Linear
   1. Linear integration setup
   2. Create MRs that are recognized and automatically linked by Linear
   3. Linear integration troubleshooting
      1. The integration configuration seems OK, but tickets stopped updating
2. Further reading

Linear

Linear integration setup

Refer Linear's documentation for GitLab integration.

Important

The GitLab installation must be reachable from Linear's 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.

Linear integration troubleshooting

Important

Linear's support team has access to internal diagnostic logs built by their engineering team for debugging and system monitoring.
Those are not exposed externally, nor are accessible through the Linear interface or API.

The integration configuration seems OK, but tickets stopped updating

Root cause: it could be that the TLS certificate used by the integrations proxy is expired.
If this is the case, Linear's support team will be able to see logs like the following:

Error fetching merge request from GitLab: request to https://gitlab.example.org/api/v4/projects/... failed, reason:
certificate has expired

Solution: make sure the certificate is still valid, and renew it if not.

Further reading

• GitLab integration
• GitLab service accounts