--- metadata: - name: generator content: Diplodoc Platform v5.47.3 alternate: - https://yandex.com.tr/support/tracker/en/user/gitlab.md title: "About Yandex\_Tracker and GitLab integration" description: "This page explains integration of Yandex\_Tracker with GitLab." --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/support/tracker/en/llms.txt # GitLab You can integrate your GitLab repository with Yandex Tracker to display links to commits and merge requests in issues. To add a commit or merge request link to an issue, specify the [issue key](*issuekey) in the commit comment or merge request description: for example, `Fixing error TEST-123`. For more information, see [Integration with repositories](https://yandex.com.tr/support/tracker/en/user/add-repository.md). * To set up links between issues in Yandex Tracker and commits, you can use one of the following methods: - Configure a webhook in the repository. We recommend using this sync method if you have an on-premises GitLab repository. This approach allows for faster data synchronization, so new commits will appear in the dedicated Yandex Tracker issue almost immediately. [Configuring a webhook for commits in the repository](#webhook) - Configure periodic repository polling. Yandex Tracker will periodically poll the repository for information about commits. You can configure this sync method for repositories hosted online or deployed on-premises. [Configuring repository polling](#poll) {% note warning "" %} When polling a repository, links to commits may appear in Yandex Tracker with a delay of up to 10 hours. {% endnote %} * To set up links between issues in Yandex Tracker and merge requests, you can create a webhook in your repository that will access the Tracker API and transmit merge request data. [Configuring a webhook for merge requests in the repository](#relation) ## Configuring a webhook for commits in the repository {#webhook} {% note warning "" %} Syncing commits via a webhook is available for on-premises repositories. {% endnote %} 1. In Yandex Tracker, obtain a URL and a token to configure the webhook: [How to obtain a URL and token](https://yandex.com.tr/support/tracker/en/user/add-repository.md#get-token). 1. Open your GitLab instance and go to the hook settings: * To enable integration for the entire [GitLab instance](https://yandex.cloud/en/docs/managed-gitlab/concepts/) (GitLab admin privileges are required): 1. In the left panel, click the **Your work** drop-down list and select **Admin Area**. 1. Go to **System Hooks**. * To enable integration for an individual project: 1. Go to the project you need. 1. In the left panel, click **Settings** and select **Webhooks**. 1. In the **URL** field, enter the URL you copied in Yandex Tracker. 1. In the **Secret token** field, enter the token you copied in Yandex Tracker. 1. In the **Trigger** section, disable all options except **Push events**. 1. In the **SSL verification** section, select **Enable SSL verification**. 1. Click **Add system hook** (**Add webhook** for an individual project). To make sure the webhook is running properly: 1. Create or select an existing issue in Yandex Tracker where you will test a link to a commit. 1. Create a commit in your repository and specify the issue key in its comment, for example, `Fixing error TEST-123`. 1. Make sure the **Commits** tab on the issue page in Yandex Tracker displays information about your commit. ## Configuring a webhook for merge requests in the repository {#relation} To set up links between issues in Yandex Tracker and merge requests, create a webhook in your GitLab repository that will access the Tracker API and transmit merge request data. To link a merge request to an issue, specify the issue key in the name or description of the new merge request. You'll find the merge request link on the issue page under **Links to external applications**. You can also enable automatic creation of issue comments with information about merge requests. Auto comments are only available when using Managed Service for GitLab. ### Create a hook for integration {#create-hook} To create a webhook for linking issues to merge requests: 1. Create a technical account in your organization that will send requests to the Yandex Tracker API: [Managing users](https://yandex.com.tr/support/tracker/en/add-users.md). 1. Obtain an OAuth token for the created technical account to access the Yandex Tracker API: [How to obtain a token](https://yandex.com.tr/support/tracker/en/api-ref/access.md#about_OAuth). 1. Check if you have access to the API using the request [Getting information about the current user](https://yandex.com.tr/support/tracker/en/api-ref/users/get-user-info.md). 1. Open a GitLab instance and go to the hook settings: * To enable integration for the entire [GitLab instance](https://yandex.cloud/en/docs/managed-gitlab/concepts/) (GitLab admin privileges are required): 1. In the left-hand panel, click the **Your work** dropdown list and select **Admin Area**. 1. Go to **System Hooks**. * To enable integration for an individual project: 1. Go to the project you need. 1. In the left-hand panel, click **Settings** and select **Webhooks**. 1. Specify the hook parameters: * **URL**: ``` https://api.tracker.yandex.net/v3/system/gitlab/receive?comments=true&= ``` Where: * `comments=true`: Enables automatic creation of comments in an issue with a link to and information about merge requests. Remove this parameter from the URL if you don't need comments. This parameter is only available for Managed Service for GitLab. * ``: It may take the following values: - `x_cloud_org_id`: For a Yandex Cloud Organization. - `x_org_id`: For a Yandex 360 for Business organization. * `` To get the organization ID, go to **Administration** → [**Organizations**](https://tracker.yandex.com/admin/orgs) and copy the value from the **ID** field. {#find-id} * **Secret token**: The technical account's OAuth token that you obtained, which looks like `OAuth `. For example: `OAuth y1_AQAD-qJScA********`. * In the **Trigger** section, disable all options except **Merge request events**. * In the **SSL verification** section, select **Enable SSL verification**. 1. Click **Add system hook** (**Add webhook** for an individual project). The **System Hooks** (**Project Hooks** for an individual project) section with information about the created hook and its parameters will appear on the page. ### Test the hook {#test-hook} 1. Click **Test** under **System Hooks** (**Project Hooks** for an individual project). 1. Select **Merge request events** from the drop-down list. A test request should return a response saying `Hook executed successfully: HTTP 204`. If the test request returns an error, the hook parameters are incorrect. ### Check the result {#test-mr} To make sure the webhook is running properly: 1. Create or select an existing issue in Yandex Tracker where you will test a link to a commit. 1. Create a merge request in your repository and specify the issue key in its name or description, for example, `Fixing error TEST-123`. 1. Make sure the **Links to external applications** tab on the issue page in Yandex Tracker displays information about your merge request. If you used Managed Service for GitLab and enabled auto comments when creating a webhook, the issue will show a comment with the merge request link and details. ### Learn more {#see-also} * [Managed Service for GitLab documentation](https://yandex.cloud/en/docs/managed-gitlab/) * [Guide on integrating GitLab with Yandex Tracker](https://yandex.cloud/en/docs/managed-gitlab/tutorials/tracker-integration). ## Configuring repository polling {#poll} ### Integrating an online repository {#repo} To connect your repository on [GitLab](https://gitlab.com) to Yandex Tracker: {% note info "" %} Private repositories can only be accessed by users logged in to GitLab (**Internal project**) or the project team (**Private project**). {% endnote %} 1. Obtain a token on GitLab to access your repository. For details on how to get a token, see the [GitLab documentation](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token). For the proper operation of Yandex Tracker, enable the **read_repository** and **read_api** options when setting up permissions. 1. Make sure you are authorized in Tracker as an [administrator](https://yandex.com.tr/support/tracker/en/role-model.md). 1. In Yandex Tracker, in the left-hand panel, click → **Administration** and then open **Repositories**. 1. Click **Add** and select **Repository**. 1. Choose GitLab in the **Platform** field. 1. Choose **gitlab.com** for the **Server address** option. 1. In the **Repository** field, enter the address in this format `https://gitlab.com//`, then specify the access token. 1. Click **Add**. 1. Make sure that the repository status in Yandex Tracker is **Connected**. ### Integrating an on-premises repository {#on-premise} Before continuing, obtain a token to access the repository. For instructions on how to obtain an OAuth token, see the [GitLab documentation](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token). For the proper operation of Yandex Tracker, enable the **read_repository** and **read_api** options when setting up permissions. To integrate an on-premises repository with Yandex Tracker: 1. Make sure you are authorized in Tracker as an [administrator](https://yandex.com.tr/support/tracker/en/role-model.md). 1. In Yandex Tracker, in the left-hand panel, click → **Administration** and then open **Repositories**. 1. Click **Add** and select **Repository**. 1. In the **Platform** field, select the type of your repository. 1. Choose **Own** for the **Server address** option. 1. In the **Repository** field, specify the URL of the repository on your server. Make sure that you connect to the server using the OAuth 2.0 technology. 1. In the **Token from platform** field, enter the token for connecting to your server. 1. Click **Add**. 1. Make sure that the repository status in Yandex Tracker is **Connected**. [*issuekey]: An issue key is a unique identifier contained in the issue link. It consists of the queue key and a number, for example `TEST-123`.