Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

Deploying GitLab Runner on a Yandex Compute Cloud virtual machine

Written by
Updated at March 6, 2026

GitLab Runner is an open-source application which executes GitLab CI/CD pipeline jobs based on instructions from a special file named .gitlab-ci.yml. You can deploy GitLab Runner not only in a Yandex Managed Service for 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.

For Yandex Managed Service for GitLab, you can also manually install GitLab Runner or automatically deploy a runner in the management console that will ensure the correct number of workers run in Compute Cloud.

Note

The feature of creating and managing runners using the management console is at the Preview stage. To request access, contact support or your account manager.

To get started with GitLab Runner using Compute Cloud:

  1. Set up your infrastructure.
  2. Get a GitLab Runner token.
  3. Deploy GitLab Runner.
  4. Create a test scenario.

If you no longer need the resources you created, delete them.

The infrastructure support cost includes:

Set up your infrastructure

  1. Create and activate a Managed Service for GitLab instance.
  2. Create a GitLab project.

Get a GitLab Runner token

You can get a token when creating a GitLab Runner in GitLab. You specify this token when deploying GitLab Runner on a Compute Cloud VM to have a runner authenticated in GitLab.

To create and configure GitLab Runner for the entire GitLab instance, proceed as follows (GitLab admin permissions required):

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

To create and set up GitLab Runner for a project, proceed as follows:

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

Deploy GitLab Runner

You can install GitLab Runner manually or deploy a runner in the management console automatically.

Install GitLab Runner on a VM manually

  1. Create a VM from a public Ubuntu 22.04 LTS image.

  2. Connect to the VM over SSH:

    ssh <login>@<VM_public_IP_address>

  3. Install the git and jq utilities:

    sudo apt-get --yes install git jq

  4. Add a repository with GitLab Runner to the package manager:

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

  5. Install GitLab Runner:

    sudo apt-get -y install gitlab-runner

  6. Register GitLab Runner:

    sudo gitlab-runner register

    The command will prompt you for additional data:

    • URL of the GitLab instance in https://<domain>/ format.
    • Previously obtained GitLab Runner token.
    • GitLab Runner description.
    • Do not specify GitLab Runner tags and the update settings (maintenance note).
    • executor: shell.

    Result:

    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

Note

The feature of creating and managing runners using the management console is at the Preview stage. To request access, contact support or your account manager.

Warning

There is a fee for using VM instances (workers) (see Compute Cloud pricing).

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

  1. Select the Managed Service for GitLab instance you need to create a runner for.

  2. Select the Runners tab.

  3. Click Create Runner.

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

  5. Optionally, enter a random decription for the runner.

  6. Enter the previously obtained GitLab Runner token.

  7. Select or create a service account for the runner.

    Note

    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, vpc.admin, and iam.serviceAccounts.user roles. For more information, see Assigning roles to a service account.

  8. Optionally, add labels to break runners into logical groups.

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

  10. Optionally, add labels for the worker.

  11. Under Computing resources, select a computing resource configuration.

  12. Under Disks and file storages, configure the boot disk:

    • Select the disk type.
    • Specify the disk size.

  13. Optionally, select or create a service account for the worker.

    Note

    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 your service account a role for the resource you want to manage.

  14. Optionally, select a security group.

  15. Click Create.

Test the runner

  • If GitLab Runner was created for the whole GitLab instance:

    1. In the bottom-left corner, click Admin.
    2. In the left-hand menu, select CI/CD → Runners.
    3. Make sure the new runner is now in the list.

  • If GitLab Runner was created for a project:

    1. Open your project.
    2. In the left-hand menu, select Settings → CI/CD.
    3. Under Runners, click Expand.
    4. Make sure the new runner has appeared in the Assigned project runners section.

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

Create a test scenario

  1. Open the GitLab project.

  2. Select Build → Pipeline editor in the left-hand menu. A page will open asking you to add a new file named .gitlab-ci.yml, in which you need to describe the scenario in YAML format.

  3. Add the scenario text:

    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

  4. Click Commit changes.

  5. Select Build → Jobs in the left-hand menu.

  6. Make sure that three jobs have the Passed status.

Delete the resources you created

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

See also

Previous
All tutorials
Next
Secure storage of GitLab CI passwords as Yandex Lockbox secrets