Contact UsGet started

Getting started with Managed Service for GitLab

Written by
Updated at November 7, 2024

To get started with the service:

  1. Create an instance.
  2. Set up a working environment.
  3. Add SSH keys to GitLab.
  4. Start using the repository.

Warning

To start working with Managed Service for GitLab, check this guide on how to migrate your projects from a GitLab custom installation to the service.

For more information about the differences between Managed Service for GitLab and the GitLab Community Edition custom installation, see the Service advantages over a GitLab custom installation section.

Getting started

  1. Go to the management console and log in to Yandex Cloud or sign up if not signed up yet.

  2. If you do not have a folder yet, create one:

    1. In the management console, select the appropriate cloud in the list on the left.

    2. At the top right, click Create folder.

    3. Enter the folder name. The naming requirements are as follows:

      • The name must be from 3 to 63 characters long.
      • It may contain lowercase Latin letters, numbers, and hyphens.
      • The first character must be a letter and the last character cannot be a hyphen.

    4. (Optional) Enter a description of the folder.

    5. Select Create a default network. This will create a network with subnets in each availability zone. Within this network, a default security group will be created, inside which all network traffic is allowed.

    6. Click Create.

  3. Make sure your account has the vpc.user role and the gitlab.editor role or higher for creating an instance.

Create an instance

Warning

Once an instance is created, you cannot change its resource configuration, i.e., instance type, disk size, and availability zone.

  1. In the management console, select the folder where you want to create a GitLab instance.

  2. Select Managed Service for GitLab.

  3. Click Create instance.

  4. Under General information:

    1. Enter the instance name. It must be unique throughout Yandex Cloud.

      • The name must be from 3 to 63 characters long.
      • It may contain lowercase Latin letters, numbers, and hyphens.
      • The first character must be a letter and the last character cannot be a hyphen.

    2. (Optional) Enter a description of the instance.

  5. Under Configuration:

    1. Select the instance type. After you create an instance, you can only change its type by contacting support.

    2. Specify the subnet where the instance will be hosted. Currently, Yandex Cloud technical restrictions do not allow selecting a subnet with an address range of 192.168.0.0/24.

      The default security group for the selected network will be used for the instance. If you cannot open the GitLab web interface after creating the instance, create a separate security group and configure it so that the rules allow incoming traffic from the required ports and IP addresses.

    3. Select the disk size. After you create an instance, you can only increase the storage size by contacting support. You cannot reduce the storage size.

    4. Specify the instance domain name: relevant DNS records will be automatically created for it in the .gitlab.yandexcloud.net domain.

      The domain name must be unique throughout Yandex Cloud.

      • Its length must be between 5 and 50 characters.
      • It may contain lowercase Latin letters, numbers, and hyphens.
      • It must not start or end with a dash character.

    5. Set up the retention period for automatic backups (in days).

    6. (Optional) Enable code approval rules. To do this, select the appropriate configuration for approval rules.

      Note

      The configuration you select affects the cost of using the instance's computing resources.

  6. Under Administrator data, specify:

    • Email: Email address of the GitLab instance administrator. This mailbox will receive an email with a link for creating a password.
    • Login: Administrator login.

  7. Click Create.

  8. Wait for the instance to get ready: its status on the Managed Service for GitLab dashboard will change to Running. This may take some time.

Note

When you create an instance in Managed Service for GitLab, it automatically generates an SSL certificate. No additional configuration for using HTTPS is required.

Set up a working environment

  1. Activate the Managed Service for GitLab instance:

    1. Follow the link you received in your administrator mailbox after creating the instance.
    2. Change the administrator password.
    3. Log in using the administrator username and password.

  2. (Optional) Create a group to host the repository project.

    If there are several projects, you might want to group users together. This will allow you to:

    • Grant rights for specific projects to each group.
    • View issues and merge requests by group.
    • View analytics on group's activities.

    For more information, see the GitLab documentation.

  3. Create an empty project to host the repository.

  4. Create users and add 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

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

    1. Open the terminal.

    2. Use the ssh-keygen command to create a new key:

      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.

    If you do not have OpenSSH installed yet, follow this guide to install it.

    1. Run cmd.exe or powershell.exe (make sure to update PowerShell before doing so).

    2. Use the ssh-keygen command to create a new key:

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

    Create keys using the PuTTY app:

    1. Download and install PuTTY.

    2. Make sure the directory where you installed PuTTY is included in PATH:

      1. Right-click My computer. Click Properties.
      2. In the window that opens, select Additional system parameters, then Environment variables (located in the lower part of the window).
      3. Under System variables, find PATH and click Edit.
      4. In the Variable value field, append the path to the directory where you installed PuTTY.

    3. Launch the PuTTYgen app.

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

    5. In Key passphrase, enter a strong password. Enter it again in the field below.

    6. Click Save private key and save the private key. Do not share its key phrase with anyone.

    7. Click Save public key and save the public key in the following file: <key_name>.pub.

  2. Launch the SSH agent:

    1. Run this command:

      ssh-agent -s

    2. For the SSH agent to start on login, add the launch command to the ~/.profile file:

      ssh-agent -s
    1. Open the Start button context menu.
    2. Select Computer Management.
    3. Go to Services and Applications → Services.
    4. Open the context menu of the SSH agent service and select Properties.
    5. On the Main tab, change the startup type from Off to Automatic.
    6. Click OK and start the service.

  3. Add a key to the SSH agent:

    ssh-add <path_to_private_key>

  4. Assign a public SSH key to the GitLab account.

  5. Check that you can connect to GitLab:

    ssh -T git@<GitLab_instance_domain>

    Example:

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

    If connecting for the first time, you will get this or similar message:

    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 it is not your first time, you will get this upon a successful connection:

    Welcome to GitLab, @<login>!

    In case of an error, run the connection in Verbose mode to get the logs:

    ssh -Tvvv git@<GitLab_instance_domain>

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

Start using the repository

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 the Git client.

  2. Clone the repository using the SSH protocol.

    What to do if you get the Permission denied (publickey) error

    When cloning, you may get this error:

    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 permissions
and the repository exists.

    If you get this error:

    1. Create and open a configuration file to set up SSH keys:

      nano ~/.ssh/config

    2. Add content to it:

      Host <GitLab_instance_domain>
   IdentityFile <path_to_private_key>

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

    3. Save the file.

    4. Clone the repository again via SSH.

  3. Go to the directory containing the repository:

    cd <project_name>

  4. Make changes to the repository files.

  5. Index and apply the changes in the local repository:

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

  6. Push changes to the remote repository:

    git push origin main
Next
All guides