---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
  - property: og:type
    content: article
  - property: article:section
    content: Интеграция с другими сервисами
  - property: og:title
    content: GitLab
  - property: article:tag
    content: Сборник инструкций
alternate:
  - https://yandex.ru/support/tracker/en/user/gitlab.md
  - https://yandex.ru/support/tracker/ru/user/gitlab.md
  - href: en/user/gitlab.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
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.ru/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.ru/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.

    [Webhook](#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.ru/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).

<!-- source: en/_includes/gitlab/test-hook.md -->
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.
<!-- endsource: en/_includes/gitlab/test-hook.md -->

## 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.

<!-- source: en/_includes/gitlab/create-hook.md -->
### 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.ru/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.ru/support/tracker/en/api-ref/access.md).
1. Check if you have access to the API using the request [Getting information about the current user](https://yandex.ru/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&<organization_type>=<organization_ID>
      ```

      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.
      * `<organization_type>`: It may take the following values:
        - `x_cloud_org_id`: For a Yandex Identity Hub.
        - `x_org_id`: For a Yandex 360 for Business organization.
      * `<organization_ID>`

         <!-- source: en/api-ref/_includes/org-id.md -->
         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}
         <!-- endsource: en/api-ref/_includes/org-id.md -->

    * **Secret token**: The technical account's OAuth token that you obtained, which looks like `OAuth <token_contents>`.
      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.
<!-- endsource: en/_includes/gitlab/create-hook.md -->

<!-- source: en/_includes/gitlab/test-hook.md -->
### 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.
<!-- endsource: en/_includes/gitlab/test-hook.md -->

<!-- source: en/_includes/gitlab/test-hook.md -->
### 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.
<!-- endsource: en/_includes/gitlab/test-hook.md -->

### 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. <!-- source: en/_includes/make-sure-admin.md -->
   Make sure you are authorized in Tracker as an [administrator](https://yandex.ru/support/tracker/en/role-model.md).
   <!-- endsource: en/_includes/make-sure-admin.md -->

1. <!-- source: en/_includes/repository-path.md -->
   In Yandex Tracker, in the left-hand panel, click ![](../_assets/svg/actions.svg)</svg> → ![](../_assets/svg/admin.svg)</svg> **Administration** and then open ![](../_assets/svg/repositories.svg)</svg> **Repositories**.
   <!-- endsource: en/_includes/repository-path.md -->

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/<repository_owner_login>/<repository_name>`, 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.

<!-- source: en/_includes/on-premise-server.md -->
To integrate an on-premises repository with Yandex Tracker:

1. <!-- source: en/_includes/make-sure-admin.md -->
   Make sure you are authorized in Tracker as an [administrator](https://yandex.ru/support/tracker/en/role-model.md).
   <!-- endsource: en/_includes/make-sure-admin.md -->

1. <!-- source: en/_includes/repository-path.md -->
   In Yandex Tracker, in the left-hand panel, click ![](../_assets/svg/actions.svg)</svg> → ![](../_assets/svg/admin.svg)</svg> **Administration** and then open ![](../_assets/svg/repositories.svg)</svg> **Repositories**.
   <!-- endsource: en/_includes/repository-path.md -->

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**.
<!-- endsource: en/_includes/on-premise-server.md -->

[*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`.