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 May 7, 2026

GitLab 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 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 via the management console to ensure the required number of workers running 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 pipeline.

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 Git and jq:

    sudo apt-get --yes install git jq

  4. Add the GitLab Runner repository 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 to enter additional data:

    • URL of the GitLab instance in https://<domain>/ format.
    • GitLab Runner token you got earlier.
    • 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.

For the managed runner to work correctly, you need to configure the network and security groups.

  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 you created the GitLab Runner 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 you created the GitLab Runner 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 you can see the new runner under Assigned project runners.

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

Create a test pipeline

  1. Open the GitLab project.

  2. 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 format.

  3. Add the pipeline configuration:

    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. In the left-hand menu, select Build → Jobs.

  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