[Yandex Cloud documentation](../index.md) > [Yandex Managed Service for GitLab](index.md) > Getting started

# Getting started with Managed Service for GitLab

To get started:
1. [Create an instance](#instance-create).
1. [Set up the runtime environment](#configure-mgl).
1. [Add SSH keys to GitLab](#ssh).
1. [Start using the repository](#start-work-with-git).

{% note warning %}

Before you begin, check [this guide](operations/instance/migration.md) on how to migrate your projects from a custom GitLab installation to Managed Service for GitLab.

{% endnote %}

For more information about the differences between Managed Service for GitLab and the custom GitLab Community Edition installation, see [Advantages over a custom GitLab installation](concepts/managed-gitlab-vs-custom-installation.md).

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

{% list tabs group=instructions %}

- Management console {#console}

  1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or sign up if you do not have an account yet.
  1. If you do not have a folder yet, create one:

     1. In the [management console](https://console.yandex.cloud), in the top panel, click ![image](../_assets/console-icons/layout-side-content-left.svg) or ![image](../_assets/console-icons/chevron-down.svg) and select the [cloud](../resource-manager/concepts/resources-hierarchy.md#cloud).
     1. To the right of the cloud name, click ![image](../_assets/console-icons/ellipsis.svg).
     1. Select ![image](../_assets/console-icons/plus.svg) **Create folder**.
     
        ![create-folder1](../_assets/resource-manager/create-folder-1.png)
     
     1. Give your [folder](../resource-manager/concepts/resources-hierarchy.md#folder) a name. The naming requirements are as follows:
     
         * Length: between 3 and 63 characters.
         * It can only contain lowercase Latin letters, numbers, and hyphens.
         * It must start with a letter and cannot end with a hyphen.
     
     1. Optionally, specify the description for your folder.
     1. Select **Create a default network**. This will create a [network](../vpc/concepts/network.md#network) with subnets in each availability zone. Within this network, you will also have a [default security group](../vpc/concepts/security-groups.md#default-security-group), within which all network traffic will be allowed.
     1. Click **Create**.
     
        ![create-folder2](../_assets/resource-manager/create-folder-2.png)

  1. [Assign](../iam/operations/roles/grant.md) the [vpc.user](../vpc/security/index.md#vpc-user) role and the [gitlab.editor role or higher](security/index.md#roles-list) to your Yandex Cloud account. These roles allow you to create an instance.

      {% note info %}
      
      If you cannot manage roles, contact your cloud or organization administrator.
      
      {% endnote %}

{% endlist %}

## Create an instance {#instance-create}

{% note warning %}

Once you have created an instance, you cannot change its network configuration, i.e., availability zone and subnet.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the management console, select the [folder](../resource-manager/concepts/resources-hierarchy.md#folder) where you want to create a [GitLab instance](concepts/index.md#instance).
  1. Navigate to **Managed Service for GitLab**.
  1. Click **Create instance**.
  1. At the top of the page:
  
     1. Enter a name for your instance. It must be unique within Yandex Cloud.
  
        * Length: between 3 and 63 characters.
        * It can only contain lowercase Latin letters, numbers, and hyphens.
        * It must start with a letter and cannot end with a hyphen.
  
     1. Optionally, enter a description for the instance.
     1. Optionally, add [labels](../resource-manager/concepts/labels.md) to break instances into logical groups.
     1. Optionally, set instance protection against accidental deletion by users.
  
  1. Under **Configuration**:
  
     1. Select the [instance type](concepts/index.md#config). After you create an instance, you can [upgrade its type](operations/instance/instance-update.md) to a higher performing one.
     1. Specify the [availability zone](../overview/concepts/geo-scope.md). After you create an instance, you cannot change its availability zone.
     1. Specify the [subnet](../vpc/concepts/network.md#subnet) to host the instance. Currently, Yandex Cloud technical restrictions do not allow selecting a subnet with the `192.168.0.0/24` address range.
     1. Select a [security group](../vpc/concepts/security-groups.md) or create a new one:
  
        1. Click **Create group**.
        1. Enter a name and description for the security group. You can add rules for the security group later in **Virtual Private Cloud**.
        1. Click **Create**.
  
        If you do not specify a separate security group, the [default security group](../vpc/concepts/security-groups.md#default-security-group) created in the instance network will apply.
        
        [Configure](operations/configure-security-group.md) your security group so that its rules allow incoming and outgoing traffic on the specified ports and IP addresses.
              
        {% note warning %}
        
        The security group's setup determines the Managed Service for GitLab instance performance and availability.
        
        {% endnote %}
        
        If you have issues with setting up a security group, contact [support](https://center.yandex.cloud/support).
  
     1. Select the [disk](../compute/concepts/disk.md) size. After you create an instance, [you can increase](operations/instance/instance-update.md) its disk size.
     1. Specify the [instance domain name](../compute/concepts/network.md#hostname): the system will automatically create the relevant DNS records for it in the `.gitlab.yandexcloud.net` domain.
  
        The domain name must be unique within Yandex Cloud.
        
        * It must be from 5 to 50 characters long.
        * It can include lowercase Latin letters, numbers, and hyphens.
        * It cannot not start or end with a hyphen.
  
     1. Set up the automatic backup retention period in days.
     1. Optionally, enable [approval rules](concepts/approval-rules.md). To do this, select the appropriate configuration for approval rules.
  
        {% note warning %}
        
        In Managed Service for GitLab, you pay for approval rules depending on your [configuration](concepts/approval-rules.md#packages). For more information, see [Yandex Managed Service for GitLab pricing policy](pricing.md).
        
        {% endnote %}
  
  1. Under **Administrator data**, specify:
     * **Email**: Email address of the GitLab instance administrator. This is the address to receive the email with a link to create a password.
     * **Login**: Administrator login.
  1. Optionally, under **Advanced settings**, enable deletion of untagged images. This setting affects the amount of free disk space on the instance.
  1. Click **Create**.
  1. Wait until the instance is ready: its status on the Managed Service for GitLab dashboard will change to **Running**. This may take a while.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../cli/quickstart.md#install).
  
  The folder used by default is the one specified when [creating](../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.
  
  1. See the description of the [CLI](../cli/index.md) command for creating a Managed Service for GitLab instance:
  
       ```bash
       yc managed-gitlab instance create --help
       ```
  
  1. Select a [subnet](../vpc/concepts/network.md#subnet):
  
      ```bash
      yc vpc subnet list
      ```
  
      Result:
  
       ```text
       +----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
       |          ID          |           NAME            |      NETWORK ID      | ROUTE TABLE ID |       ZONE        |      RANGE      |
       +----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
       | e9bnlm18l70a******** |   default-ru-central1-a   | enpe3m3fa00u******** |                |   ru-central1-a   | [10.128.0.0/24] |
       +----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
       ```
  
  1. Create a GitLab instance (this example does not use all available parameters):
  
      ```bash
      yc managed-gitlab instance create \
        --name first-instance \
        --resource-preset-id <host_class> \
        --disk-size <disk_size_in_GB> \
        --admin-login <admin_login> \
        --admin-email <admin_email_address> \
        --domain-prefix <instance_domain_name> \
        --deletion-protection \
        --approval-rules <approval_rule_configuration> \
        --subnet-id <subnet_ID>
      ```
  
      Where:
      * `--name`: Instance name, unique within Yandex Cloud. Follow these naming requirements:
  
        * Length: between 3 and 63 characters.
        * It can only contain lowercase Latin letters, numbers, and hyphens.
        * It must start with a letter and cannot end with a hyphen.
  
      * `--resource-preset-id`: Host class. It determines the configuration of the VM to host the GitLab instance. The possible values are:
        * `s2.micro`: 2 vCPUs, 8 GB RAM
        * `s2.small`: 4 vCPUs, 16 GB RAM
        * `s2.medium`: 8 vCPUs, 32 GB RAM
        * `s2.large`: 16 vCPUs, 64 GB RAM
      * `--disk-size`: Disk size, in GB.
      * `--admin-login`: GitLab instance admin login.
      * `--admin-email`: Instance admin email address. This is the address to receive the email with a link to create a password.
      * `--domain-prefix`: [Instance domain name](../compute/concepts/network.md#hostname). The system will automatically create the relevant DNS records for it in the `.gitlab.yandexcloud.net` domain.
  
        The domain name must be unique within Yandex Cloud.
        
        * It must be from 5 to 50 characters long.
        * It can include lowercase Latin letters, numbers, and hyphens.
        * It cannot not start or end with a hyphen.
  
      * `--deletion-protection`: Instance protection against accidental deletion by users.
      * `--approval-rules`: [Approval rule](concepts/approval-rules.md) configuration. The possible values are:
        * `BASIC`
        * `STANDARD`
        * `ADVANCED`
  
        {% note warning %}
        
        In Managed Service for GitLab, you pay for approval rules depending on your [configuration](concepts/approval-rules.md#packages). For more information, see [Yandex Managed Service for GitLab pricing policy](pricing.md).
        
        {% endnote %}
  
      * `--subnet-id`: ID of the selected subnet.
  
      Result:
  
      ```text
      id: c17c60tpadua********
      folder_id: b1g2slt7p9ug********
      created_at: "2025-07-20T18:34:16.078Z"
      updated_at: "2025-07-20T18:34:16.078Z"
      name: test-cli
      resource_preset_id: s2.small
      disk_size: "107374182400"
      status: RUNNING
      admin_login: admin-gl
      admin_email: user@example.com
      domain: test-domain-user.gitlab.yandexcloud.net
      subnet_id: e9b4rrpuu2a********
      backup_retain_period_days: "7"
      deletion_protection: true
      approval_rules_id: BASIC
      gitlab_version: 17.11.6
      ```
  
      For more information about this command, see the [CLI reference](cli-ref/instance/create.md).

{% endlist %}

{% note info %}

When you create an instance in Managed Service for GitLab, the system automatically generates an SSL certificate. Using HTTPS requires no advanced setup.

{% endnote %}

## Set up the runtime environment {#configure-mgl}

1. Activate your Managed Service for GitLab instance:
   1. Follow the link you received in your administrator mailbox after creating the instance.
   1. Change the administrator password.
   1. Log in using the administrator username and password.
1. Optionally, [create a group](https://docs.gitlab.com/ee/user/group/#create-a-group) to host the repository project.

   When working with multiple projects, consider grouping users together. This will allow you to:

   * Grant permissions for specific projects to each group.
   * View issues and merge requests by group.
   * View group activity analytics.

   For more information, see [this GitLab guide](https://docs.gitlab.com/ee/user/group/).

1. [Create an empty project](https://docs.gitlab.com/ee/user/project/) to host the repository.
1. [Create users and add](operations/create-user.md) them to a group or project with the `Maintainer` or `Owner` role.

   You can only add your team members to a group or project by creating GitLab accounts for them.

## Add SSH keys to GitLab {#ssh}

1. Create a pair of public and private SSH keys for the GitLab account:

    {% list tabs group=operating_system %}

    - Linux/macOS {#linux-macos}

      1. Open the terminal.
      1. Use the `ssh-keygen` command to create a new key:
      
          ```bash
          ssh-keygen -t ed25519 -C "<optional_comment>"
          ```
      
          You can specify an empty string in the `-C` parameter to avoid adding a comment, or you may not specify the `-C` parameter at all: in this case, a default comment will be added.
      
          After running this command, you will be prompted to specify the name and path to the key files, as well as enter the password for the private key. If you only specify the name, the key pair will be created in the current directory. The public key will be saved in a file with the `.pub` extension, while the private key, in a file without extension.
      
          By default, the command prompts you to save the key under the `id_ed25519` name in the following directory: `/home/<username>/.ssh`. If there is already an SSH key named `id_ed25519` in this directory, you may accidentally overwrite it and lose access to the resources it is used in. Therefore, you may want to use unique names for all SSH keys.

    - Windows 10/11 {#windows}

      If you do not have [OpenSSH](https://en.wikipedia.org/wiki/OpenSSH) installed yet, follow this [guide](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui) to install it.
      
      1. Run `cmd.exe` or `powershell.exe` (make sure to update PowerShell before doing so).
      1. Use the `ssh-keygen` command to create a new key:
      
          ```shell
          ssh-keygen -t ed25519 -C "<optional_comment>"
          ```
      
          You can specify an empty string in the `-C` parameter to avoid adding a comment, or you may not specify the `-C` parameter at all: in this case, a default comment will be added.
      
          After running this command, you will be prompted to specify the name and path to the key files, as well as enter the password for the private key. If you only specify the name, the key pair will be created in the current directory. The public key will be saved in a file with the `.pub` extension, while the private key, in a file without extension.
      
          By default, the command prompts you to save the key under the `id_ed25519` name in the following folder: `C:\Users\<username>/.ssh`. If there is already an SSH key named `id_ed25519` in this directory, you may accidentally overwrite it and lose access to the resources it is used in. Therefore, you may want to use unique names for all SSH keys.

    - Windows 7/8 {#windows7-8}

      Create keys using the PuTTY app:
      
      1. [Download](https://www.putty.org) and install PuTTY.
      1. Add the folder with PuTTY to the `PATH` variable:
      
          1. Click **Start** and type **Change system environment variables** in the Windows search bar.
          1. Click **Environment Variables...** at the bottom right.
          1. In the window that opens, find the `PATH` parameter and click **Edit**.
          1. Add your folder path to the list.
          1. Click **OK**.
      
      1. Launch the PuTTYgen app.
      1. Select **EdDSA** as the pair type to generate. Click **Generate** and move the cursor in the field above it until key creation is complete.
      
          ![ssh_generate_key](../_assets/compute/ssh-putty/ssh_generate_key.png)
      
      1. In **Key passphrase**, enter a strong password. Enter it again in the field below.
      1. Click **Save private key** and save the private key. Do not share its key phrase with anyone.
      1. Click **Save public key** and save the public key to a file named `<key_name>.pub`.

    {% endlist %}

1. Launch the SSH agent:
   
   {% list tabs group=operating_system %}
   
   - Linux/MacOS {#linux-macos}
   
      1. Run this command:
   
         ```bash
         ssh-agent -s
         ```
   
      1. For the SSH agent to start on login, add the launch command to the `~/.profile` file:
   
         ```bash
         ssh-agent -s
         ```
   
   - Windows {#windows}
   
      1. Open the **Start** button context menu.
      1. Select **Computer Management**.
      1. Go to **Services and Applications** → **Services**.
      1. Open the context menu of the **SSH agent** service and select **Properties**.
      1. On the **Main** tab, change the startup type from **Off** to **Automatic**.
      1. Click **OK** and start the service.
   
   {% endlist %}
1. Add a key to the SSH agent:

   ```bash
   ssh-add <private_key_path>
   ```

1. [Assign a public SSH key](https://docs.gitlab.com/ee/user/ssh.html#add-an-ssh-key-to-your-gitlab-account) to the GitLab account.
1. Check that you can connect to GitLab:

   ```bash
   ssh -T git@<GitLab_instance_domain>
   ```

   Here is an example:

   ```bash
   ssh -T git@example.gitlab.yandexcloud.net
   ```

   If this is your first time connecting, you will see a message like this:

   ```text
   The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established.
   ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
   Are you sure you want to continue connecting (yes/no)? yes
   Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hosts.
   ```

   Type `yes` and press **Enter**.

   If you have connected before, you will get this message upon successful connection:

   ```text
   Welcome to GitLab, @<login>!
   ```

   In case of an error, start the connection in verbose mode to get the logs:

   ```bash
   ssh -Tvvv git@<GitLab_instance_domain>
   ```

Ask each member of your group or project to create an SSH key pair in this manner and assign the public key to their account in GitLab.

## Start using the repository {#start-work-with-git}

To start working with a local copy of your repository using the account you created, follow the steps below on your local computer:

1. [Install Git](https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html#install-git).
1. [Clone the repository](https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html#clone-a-repository) over SSH.

   {% cut "What to do if you get the `Permission denied (publickey)` error" %}

   When cloning, you may get this error:

   ```text
   Cloning into '<project_name>'...
   git@<GitLab_instance_domain>: Permission denied (publickey).
   fatal: Could not read from remote repository.

   Please make sure you have the correct access rights
   and the repository exists.
   ```

   If you get this error:

   1. Create and open a configuration file for SSH key setup:

      ```bash
      nano ~/.ssh/config
      ```

   1. Add this content to it:

      ```bash
      Host <GitLab_instance_domain>
         IdentityFile <private_key_path>
      ```

      In the `IdentityFile` parameter, specify the absolute path to the private key you created for the GitLab project.

   1. Save the file.
   1. Clone the repository over SSH again.

   {% endcut %}

1. Go to the repository directory:

   ```bash
   cd <project_name>
   ```

1. Make changes to the repository files.
1. [Index and commit the changes](https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html#add-and-commit-local-changes) in the local repository:

   ```bash
   git add . && git commit -m "<commit_name>"
   ```

1. Push the changes to the remote repository:

   ```bash
   git push origin main
   ```