From 0fcd883e8f57823165d7f58483770e58f1164ac4 Mon Sep 17 00:00:00 2001 From: Michele Cereda Date: Mon, 30 Jun 2025 00:02:58 +0200 Subject: [PATCH] chore(kb/gitlab): add integrations --- knowledge base/gitlab/README.md | 2 + knowledge base/gitlab/integrations.md | 96 +++++++++++++++++++++++++++ snippets/git.sh | 4 +- 3 files changed, 101 insertions(+), 1 deletion(-) create mode 100644 knowledge base/gitlab/integrations.md diff --git a/knowledge base/gitlab/README.md b/knowledge base/gitlab/README.md index 8b4e5bf..b93425e 100644 --- a/knowledge base/gitlab/README.md +++ b/knowledge base/gitlab/README.md @@ -877,6 +877,7 @@ Solution: set the correct ownership with - [Elasticsearch] - [CODEOWNERS syntax] - [GitLab CLI][glab] +- [Integrations] ### Sources @@ -921,6 +922,7 @@ Solution: set the correct ownership with [buildah]: ../buildah.md [glab]: glab.md +[integrations]: integrations.md [kaniko]: ../kaniko.md [self-hosting]: ../self-hosting.md diff --git a/knowledge base/gitlab/integrations.md b/knowledge base/gitlab/integrations.md new file mode 100644 index 0000000..6bfc484 --- /dev/null +++ b/knowledge base/gitlab/integrations.md @@ -0,0 +1,96 @@ +# GitLab integrations + +1. [Linear](#linear) + 1. [Integration setup](#integration-setup) + 1. [Create MRs that are recognized and automatically linked by Linear](#create-mrs-that-are-recognized-and-automatically-linked-by-linear) +1. [Further reading](#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][gitlab service accounts]'s +[personal access token][gitlab personal access tokens], or a +[project-specific access token][gitlab project access tokens].\ +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`. +1. \[optional but suggested] Create Linear's [service account][gitlab service accounts]. +1. Create the API access token in one's GitLab instance. +1. Navigate to [Linear's _Settings_ > _Features_ > _Integrations_ > _GitLab_][linear's gitlab integration's settings]. +1. Click _Enable_ to launch the set-up pop-up. +1. Enter the access token. +1. \[if self-hosted] Enter the **public** GitLab URL without any path. +1. Click Connect. +1. Linear will generate the Webhook URL after it validates the access token. +1. 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. + +1. Enable the following triggers for the webhook: + + - _Push events_. + - _Comments_. + - _Merge request events_. + - _Pipeline events_. + +1. Ensure the _Enable SSL verification_ checkbox is checked under _SSL verification_. +1. Click _Save changes_. + +
+ +### Create MRs that are recognized and automatically linked by Linear + +One does need to follow a bit [Linear's documentation][link merge requests⁠] 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. +1. Create a branch using the format configured in [Linear's GitLab integration's settings]. +1. Make your changes in that branch, then push it. +1. When creating the MR for the branch: + + - Add the Linear issue's ID to the MR title. + - Use [one or more the magic words][use a magic word] Linear requires in the description.\ + This works for linking multiple issues. + +1. Enjoy the issue's status changing automatically when the MR is closed. + +## Further reading + +- [GitLab integration] +- [GitLab service accounts] + + + +[GitLab integration]: https://linear.app/docs/gitlab +[GitLab personal access tokens]: https://docs.gitlab.com/user/profile/personal_access_tokens/ +[GitLab project access tokens]: https://docs.gitlab.com/user/project/settings/project_access_tokens/ +[GitLab service accounts]: https://docs.gitlab.com/user/profile/service_accounts/ +[Linear's GitLab integration's settings]: https://linear.app/settings/integrations/gitlab +[Linear]: https://linear.app/ +[Link Merge Requests⁠]: https://linear.app/docs/gitlab#link-merge-requests +[Use a magic word]: https://linear.app/docs/gitlab#use-a-magic-word diff --git a/snippets/git.sh b/snippets/git.sh index 5513ad7..f9745be 100644 --- a/snippets/git.sh +++ b/snippets/git.sh @@ -77,12 +77,14 @@ git push origin --delete 'master' # create patches from the last commit git format-patch -n HEAD^ -git format-patch HEAD^ -o './patchfile.patch' +git format-patch HEAD^ -o './patchDir' git format-patch HEAD~1 --stdout # create patches from specific commits git format-patch -1 '3918a1d036e74d47a5c830e4bbabba6f507162b1' +# apply patches +git apply 'patchDir/patchFile.patch' ### # Take actions on multiple repositories