[Yandex Cloud documentation](../../index.md) > [Tutorials](../index.md) > [Development and testing](index.md) > Deploying GitLab Runner on a Compute Cloud virtual machine

# Deploying GitLab Runner on a Yandex Compute Cloud virtual machine

[GitLab Runner](https://docs.gitlab.com/runner/) is an open-source application that runs GitLab CI/CD pipeline jobs using instructions in a dedicated file named `.gitlab-ci.yml`. You can deploy GitLab Runner not only in a [Yandex Managed Service for Kubernetes cluster](../../managed-kubernetes/concepts/index.md#kubernetes-cluster) but also on a Compute Cloud virtual machine, which is an easier and cheaper option.

For a custom (self-managed) GitLab installation, you can manually install GitLab Runner on a Compute Cloud [VM](../../compute/concepts/vm.md).

For Yandex Managed Service for GitLab, you can also manually install GitLab Runner or automatically deploy a [runner](../../managed-gitlab/concepts/index.md#runners) via the [management console](https://console.yandex.cloud) to ensure the required number of workers running in Compute Cloud.

{% note info %}

The feature of creating and managing runners using the management console is at the [Preview](../../overview/concepts/launch-stages.md) stage. To request access, contact [support](https://center.yandex.cloud/support) or your account manager.

{% endnote %}

To get started with GitLab Runner using Compute Cloud:

1. [Set up your infrastructure](#infra).
1. [Get a GitLab Runner token](#gitlab-token).
1. [Deploy GitLab Runner](#deploy-glr).
1. [Create a test pipeline](#example).

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

## Required paid resources {#paid-resources}

The infrastructure support cost includes:

* Fee for [disks](../../compute/concepts/disk.md) and continuously running VMs (see [Yandex Compute Cloud pricing](../../compute/pricing.md)).
* Fee for a [public IP address](../../vpc/concepts/address.md#public-addresses) (see [Yandex Virtual Private Cloud pricing](../../vpc/pricing.md)).

## Set up your infrastructure {#infra}

1. [Create and activate](../../managed-gitlab/operations/instance/instance-create.md) a Managed Service for GitLab instance.
1. [Create a GitLab project](https://docs.gitlab.com/ee/user/project/).

## Get a GitLab Runner token {#gitlab-token}

You can get a token when creating a GitLab Runner in GitLab. You specify this token when [deploying GitLab Runner](#deploy-glr) on a Compute Cloud VM to have a runner authenticated in GitLab.

To create and configure GitLab Runner for the entire [GitLab instance](../../managed-gitlab/concepts/index.md#instance), proceed as follows (GitLab admin permissions required):

1. Open GitLab.
1. In the bottom-left corner, click **Admin**.
1. In the left-hand menu, select **CI/CD** → **Runners**.
1. Click **New instance runner** and create a new GitLab Runner.
1. Save the value of the `Runner authentication token` parameter.

To create and set up GitLab Runner for a [project](https://docs.gitlab.com/ee/user/project/), proceed as follows:

1. Open GitLab.
1. Select a project.
1. In the left-hand menu, select **Settings** → **CI/CD**.
1. Under **Runners**, click **Expand**.
1. Click **New project runner** and create a new GitLab Runner.
1. Save the value of the `Runner authentication token` parameter.

## Deploy GitLab Runner {#deploy-glr}

You can [install GitLab Runner manually](#install) or [deploy a runner in the management console automatically](#create-runner).

### Install GitLab Runner on a VM manually {#install}

1. [Create a VM](../../compute/operations/vm-create/create-linux-vm.md) from a public Ubuntu 22.04 LTS image.

1. [Connect](../../compute/operations/vm-connect/ssh.md#vm-connect) to the VM over SSH:

   ```bash
   ssh <login>@<VM_public_IP_address>
   ```

1. Install Git and `jq`:

   ```bash
   sudo apt-get --yes install git jq
   ```

1. Add the GitLab Runner repository to the package manager:

   ```bash
   curl --location https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
   ```

1. Install GitLab Runner:

   ```bash
   sudo apt-get -y install gitlab-runner
   ```

1. Register GitLab Runner:

   ```bash
   sudo gitlab-runner register
   ```

   The command will prompt you to enter additional data:

   * URL of the GitLab instance in `https://<domain>/` format.
   * GitLab Runner token you [got earlier](#gitlab-token).
   * GitLab Runner description.
   * Do not specify GitLab Runner tags and the update settings (`maintenance note`).
   * `executor`: `shell`.

   Result:

   ```text
   Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

   Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"
   ```

### Create a runner using the management console {#create-runner}

{% note info %}

The feature of creating and managing runners using the management console is at the [Preview](../../overview/concepts/launch-stages.md) stage. To request access, contact [support](https://center.yandex.cloud/support) or your account manager.

{% endnote %}

{% note warning %}

There is a fee for using VM instances (workers) (see [Compute Cloud pricing](../../compute/pricing.md)).

{% endnote %}

The feature of creating runners from the management console is only available for Managed Service for GitLab instances.

For the managed runner to work correctly, you need to [configure](../../managed-gitlab/concepts/index.md#networking-gl-mr) the network and security groups.

{% list tabs group=instructions %}

- Management console {#console}

  1. Select the Managed Service for GitLab instance you need to create a runner for.
  1. Select the **Runners** tab.
  1. Click **Create Runner**.
  1. Enter a name for the runner:
      * The name must be 2 to 63 characters long.
      * 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 random decription for the runner.
  1. Enter the [previously obtained](#gitlab-token) GitLab Runner token.
  1. Select or create a [service account](../../iam/concepts/users/service-accounts.md) for the runner.

      {% note info %}
      
      This service account will be used only to create the VM and will not be linked to it. The service account must have the [compute.admin](../../compute/security/index.md#compute-admin), [vpc.admin](../../vpc/security/index.md#vpc-admin), and [iam.serviceAccounts.user](../../iam/security/index.md#iam-serviceAccounts-user) roles. For more information, see [Assigning roles to a service account](../../iam/operations/sa/assign-role-for-sa.md).
      
      {% endnote %}

  1. Optionally, add [labels](../../resource-manager/concepts/labels.md) to break runners into logical groups.
  1. Under **Autoscale settings**, specify:

      * **Minimum workers**: Number of workers that are always running and ready to execute jobs. Default value: `1`; minimum: `0`; maximum: `10`.
      * **Maximum workers**: Maximum number of workers that can be created to execute jobs. Default value: `3`; minimum: `1`; maximum: `30`. The maximum number of workers cannot be less than the minimum number.
      * **Maximum worker downtime, in minutes**: Maximum idle time after which the additionally created worker will be deleted. Default value: `10`; minimum: `0`.
      * **Maximum number of jobs per worker**: Maximum number of jobs after which the worker will be deleted. Default value: `100`; minimum: `0`.
      * **Number of parallel tasks per worker**: Number of parallel jobs per worker. Default value: `1`; minimum: `0`.

  1. Optionally, add labels for the worker.
  1. Under **Computing resources**, select a computing resource configuration.
  1. Under **Disks and file storages**, configure the boot disk:
      * Select the [disk type](../../compute/concepts/disk.md#disks_types).
      * Specify the disk size.
  1. Optionally, select or create a service account for the worker.

      {% note info %}
      
      This service account will be associated with the worker VM. The worker can use the account to authenticate in the Yandex Cloud API and access cloud resources.
      
      [Assign](../../iam/operations/sa/assign-role-for-sa.md) your service account a role for the resource you want to manage.
      
      {% endnote %}

  1. Optionally, select a [security group](../../vpc/concepts/security-groups.md).
  1. Click **Create**.

{% endlist %}

#### Test the runner {#view-runner}

{% list tabs %}

- In GitLab

    * If you created the GitLab Runner for the whole GitLab instance:
        1. In the bottom-left corner, click **Admin**.
        1. In the left-hand menu, select **CI/CD** → **Runners**.
        1. Make sure the new runner is now in the list.

    * If you created the GitLab Runner for a project:
        1. Open your project.
        1. In the left-hand menu, select **Settings** → **CI/CD**.
        1. Under **Runners**, click **Expand**.
        1. Make sure you can see the new runner under **Assigned project runners**.

- In Compute Cloud

    Make sure the new VMs with the `runner-` name prefix have appeared in the **Virtual machines** section.

{% endlist %}

## Create a test pipeline {#example} 

1. Open the GitLab project.

1. In the left-hand menu, select **Build** → **Pipeline editor**. You will see a page prompting you to add a new file named `.gitlab-ci.yml`, where you need to describe the pipeline in [YAML](https://yaml.org/) format.

1. Add the pipeline configuration:

    ```yaml
    build:
    stage: build
    script:
      - echo "Hello, $GITLAB_USER_LOGIN!"

    test:
    stage: test
    script:
      - echo "This job tests something"

    deploy:
    stage: deploy
    script:
      - echo "This job deploys something from the $CI_COMMIT_BRANCH branch."
    environment: production
    ```

1. Click **Commit changes**.

1. In the left-hand menu, select **Build** → **Jobs**.

1. Make sure that three jobs have the `Passed` status.

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

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them:

* [GitLab instance](../../managed-gitlab/operations/instance/instance-delete.md)
* [VM with GitLab Runner](../../compute/operations/vm-control/vm-delete.md)
* [Service account](../../iam/operations/sa/delete.md)

### See also {#see-also}

* [Managed runners](../../managed-gitlab/concepts/index.md#managed-runners)
* [Working with a managed runner](../../managed-gitlab/operations/runner.md)