[Yandex Cloud documentation](../../index.md) > [Tutorials](../index.md) > [Development and testing](index.md) > GitLab integration with Tracker

# GitLab integration with Yandex Tracker

# GitLab integration with Yandex Tracker


In [Tracker issues](https://yandex.ru/support/tracker/ruabout-tracker#zadacha), you can automatically add links to GitLab [merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/) by specifying the relevant issue [key](https://yandex.ru/support/tracker/ruglossary#key) in the name or description of a new merge request. The links will be available in the [Links to external applications](https://yandex.ru/support/tracker/ruexternal-links) section.

You can also enable automatic issue comments with merge request details. Auto comments are only available for [Managed Service for GitLab](../../managed-gitlab/index.md).

To set up integration with GitLab in Tracker:

1. [Enable Yandex Tracker](#enable-tracker).
1. [Create a GitLab instance](#create-gitlab).
1. [Optionally, create a GitLab project](#create-project).
1. [Create a hook for integration](#create-hook).
1. [Test the hook](#test-hook).
1. [Check the result](#check-result).

If you no longer need the resources you created, [delete them](#clear-out).

## Getting started {#before-you-begin}

Sign up for Yandex Cloud and create a [billing account](../../billing/concepts/billing-account.md):
1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account.
1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../billing/quickstart/index.md) and [link](../../billing/operations/pin-cloud.md) a cloud to it.

If you have an active billing account, you can create or select a [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud).

[Learn more about clouds and folders here](../../resource-manager/concepts/resources-hierarchy.md).

### Required paid resources {#paid-resources}

The infrastructure support cost includes:

* Fee for a [disk](../../compute/concepts/disk.md) and a continuously running VM (see [Yandex Compute Cloud pricing](../../compute/pricing.md)).
* Fee for the number of Tracker users with full access if there are more than 5 of them (see [Tracker pricing](https://yandex.ru/support/tracker/rucloud/pricing)).
* Fee for a [public IP address](../../vpc/concepts/address.md#public-addresses) (see [Yandex Virtual Private Cloud pricing](../../vpc/pricing.md)).

## Enable Yandex Tracker {#enable-tracker}

[Enable Tracker](https://yandex.ru/support/tracker/ruenable-tracker) for your [Yandex Cloud organization](../../organization/index.md).

## Create a GitLab instance {#create-gitlab}

Create a [Managed Service for GitLab instance](../../managed-gitlab/concepts/index.md#instance) or a [VM](../../compute/concepts/vm.md) with a [GitLab image](../../compute/concepts/image.md).

{% list tabs group=gl_installation %}

- Managed Service for GitLab instance {#instance-mgl}

    Create a Managed Service for GitLab instance by following [this guide](../../managed-gitlab/quickstart.md#instance-create).

- VM with a GitLab image {#gl-image-vm}

    Launch GitLab on a VM with a [public IP address](../../vpc/concepts/address.md#public-addresses).

    1. On the [folder dashboard](../../resource-manager/concepts/resources-hierarchy.md#folder) in the [management console](https://console.yandex.cloud), click **Create resource** and select `Virtual machine instance`.
    1. Under **Boot disk image**, in the **Product search** field, enter `Gitlab` and select a public [GitLab](https://yandex.cloud/en/marketplace/products/yc/gitlab) image.
    1. Under **Location**, select the [availability zone](../../overview/concepts/geo-scope.md) where your VM will reside. If you are not sure which one to choose, leave the default.
    1. Under **Computing resources**, navigate to the `Custom` tab and specify the [platform](../../compute/concepts/vm-platforms.md), number of vCPUs, and amount of RAM:
    
        * **Platform**: `Intel Ice Lake`.
        * **vCPU**: `4`.
        * **Guaranteed vCPU performance**: `100%`.
        * **RAM**: `8 GB`.
    
    1. Under **Network settings**:
        
        * In the **Subnet** field, select the network and subnet to connect your VM to. If the relevant [network](../../vpc/concepts/network.md#network) or [subnet](../../vpc/concepts/network.md#subnet) is missing, [create it](../../vpc/operations/subnet-create.md).
        * In the **Public IP address** field, keep `Auto` to assign the VM a random external IP address from the Yandex Cloud pool or select a static address from the list if you reserved one in advance.
    
    1. Under **Access**, select **SSH key** and specify the VM access credentials:
    
        * In the **Login** field, enter the username. Do not use `root` or other OS-reserved usernames. To perform operations requiring root privileges, use the `sudo` command.
        * In the **SSH key** field, select the SSH key saved in your [organization user](../../organization/concepts/membership.md) profile.
          
          If there are no SSH keys in your profile or you want to add a new key:
          
          1. Click **Add key**.
          1. Enter a name for the SSH key.
          1. Select one of the following:
          
              * `Enter manually`: Paste the contents of the public SSH key. You need to [create](../../compute/operations/vm-connect/ssh.md#creating-ssh-keys) an SSH key pair on your own.
              * `Load from file`: Upload the public part of the SSH key. You need to create an SSH key pair on your own.
              * `Generate key`: Automatically create an SSH key pair.
              
                When adding a new SSH key, an archive containing the key pair will be created and downloaded. In Linux or macOS-based operating systems, unpack the archive to the `/home/<user_name>/.ssh` directory. In Windows, unpack the archive to the `C:\Users\<user_name>/.ssh` directory. You do not need additionally enter the public key in the management console.
          
          1. Click **Add**.
          
          The system will add the SSH key to your organization user profile. If the organization has [disabled](../../organization/operations/os-login-access.md) the ability for users to add SSH keys to their profiles, the added public SSH key will only be saved in the user profile inside the newly created resource.
    
    1. Under **General information**, specify the VM name: `ci-tutorial-gitlab`.
    1. Click **Create VM**.
    
    It may take a few minutes to create your VM. When the VM status changes to `RUNNING` and GitLab starts, configure its settings.

{% endlist %}

## Optionally, create a GitLab project {#create-project}

To set up integration for an individual GitLab project, create one.

{% list tabs group=gl_installation %}

- Managed Service for GitLab instance {#instance-mgl}

    1. Log in to the [Managed Service for GitLab instance](../../managed-gitlab/concepts/index.md#instance) web UI.
    1. Click **Create a project**.
    1. Click **Create blank project**.
    1. Fill out the fields as follows:
        * **Project name**: Enter a name for the project.
        * **Project URL**: Select the admin user in the field next to the Managed Service for GitLab instance FQDN.

        Leave the other fields unchanged.
    1. Click **Create project**.

- VM with a GitLab image {#gl-image-vm}

    1. Navigate to Yandex Compute Cloud.
    1. Select the created [VM](../../compute/concepts/vm.md) and copy its [public IP address](../../vpc/concepts/address.md#public-addresses).
    1. [Connect](../../compute/operations/vm-connect/ssh.md) to the VM over SSH.
    1. Get the GitLab administrator password with the following VM command:

        ```bash
        sudo cat /etc/gitlab/initial_root_password
        ```

    1. Copy the password without spaces from the `Password` line to the clipboard or a separate file.
    1. In your browser, open `http://<VM_public_IP_address>`. This will take you to the GitLab web UI.
    1. Log in as the administrator:
        * **Username or email**: `root`.
        * **Password**: Password you copied in the previous step.

        If you are unable to log in, [reset the administrator password](https://docs.gitlab.com/ee/security/reset_user_password.html#reset-your-root-password).
    1. [Change the administrator password](https://docs.gitlab.com/ee/user/profile/user_passwords.html#change-your-password).
    1. Log in as the administrator with the new password.
    1. Select **Create a project**.
    1. Name the project.
    1. Click **Create project**.

{% endlist %}

## Create a hook for integration {#create-hook}

### Create a hook for integration {#create-hook}

To link GitLab merge requests to Tracker issues, create a hook:

1. If you do not yet have an OAuth token for using the Tracker API, [get one](https://yandex.ru/support/tracker/ruconcepts/access#section_about_OAuth).

    {% note warning %}

    To work with the Tracker API, users must have relevant permissions in Tracker. To set up the integration, make sure you have permission to change the queue settings. For more on access permissions, see [this section](https://yandex.ru/support/tracker/rurole-model).

    {% endnote %}

1. Check if you have access to the API by [requesting information about the current user](https://yandex.ru/support/tracker/ruget-user-info).
1. Open the GitLab instance and go to the hook settings:
    * To enable integration for the entire [GitLab instance](../../managed-gitlab/concepts/index.md) (the GitLab admin privileges are required):
        1. In the left-hand 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-hand panel, click **Settings** and select **Webhooks**.
1. Configure the hook as follows:
    * **URL**: `https://api.tracker.yandex.net/v2/system/gitlab/receive?comments=true&<organization_type>=<organization_ID>`.

        Where:

        * `comments=true`: Enables automatic issue comments with merge request links and details. Disable it if commenting is not required. This parameter is only available for Managed Service for GitLab.
        * `<organization_type>`: It may take the following values:

            * `x_cloud_org_id`: If the type of your organization is Yandex Identity Hub.
            * `x_org_id`: If the type of your organization is Yandex 360 for Business or both Yandex 360 for Business and Yandex Identity Hub.

        * `<organization_ID>`: ID of the organization on the [Tracker organizations page](https://tracker.yandex.com/admin/orgs).

    * **Secret token**: OAuth token of the bot that will add the links, in `OAuth <token_contents>` format.
      For example: `OAuth y1_AQAD-qJScAAAEKEQbBNnChvfBIqR_yEQl_HMO0********`.
    * 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 page will display the **System Hooks** section (**Project Hooks** for an individual project), showing the created hook and its settings.

## Test the hook {#test-hook}

### Test the hook {#test-hook}

1. Under **System Hooks** (**Project Hooks** for an individual project), click **Test**.
1. Select **Merge request events** from the drop-down list.

The test request should return this response: `Hook executed successfully: HTTP 204`. If the test request returns an error, the hook settings are incorrect.

## Check the result {#check-result}

1. [Create an issue](https://yandex.ru/support/tracker/ruuser/create-ticket#create-task) in Tracker.
1. [Create a merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) in GitLab and specify the [issue key](https://yandex.ru/support/tracker/ruglossary#key) in its name or description.
1. Make sure a link to the merge request from GitLab appears in the Tracker issue under [Links to external applications](https://yandex.ru/support/tracker/ruexternal-links).

    If you used Managed Service for GitLab and enabled auto comments when [creating the hook](#create-hook), the issue will show a comment with the merge request link and details.

## Delete the resources you created {#clear-out}

Delete the resources you no longer need to avoid paying for them:

1. [Delete the Managed Service for GitLab instance](../../managed-gitlab/operations/instance/instance-delete.md) or the [GitLab VM](../../compute/operations/vm-control/vm-delete.md).
1. If you reserved a public static IP address for the VM, release and [delete it](../../vpc/operations/address-delete.md).