Deploying GitLab Runner on a Compute Cloud virtual machine

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.

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.

Required paid resourcesRequired paid resources

The infrastructure support cost includes:

• Fee for disks and continuously running VMs (see Yandex Compute Cloud pricing).
• Fee for using a public IP address (see Yandex Virtual Private Cloud pricing).

Set up your infrastructureSet up your infrastructure

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

Get a GitLab Runner tokenGet a GitLab Runner token

To configure GitLab Runner for the whole GitLab instance, proceed as follows (GitLab administrator access 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 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 RunnerDeploy GitLab Runner

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

Install GitLab Runner on a VM manuallyInstall 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 consoleCreate a runner using the management console

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 created earlier.

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. Enter the previously obtained GitLab Runner token.

6. Select or create a service account. This account will be used only to create the VM and will not be linked to it. The service account must have the following roles: compute.admin, vpc.admin, and iam.serviceAccounts.user.

7. Optionally, add labels for the runner.

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

   Note

   Workers are Compute Cloud VMs. You pay for them according to the Compute Cloud pricing policy.

9. Optionally, add labels for the worker.

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

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

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

12. Click Create.

13. Make sure the runner works:

    • In GitLab:

      • 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 the 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.

    • In Compute Cloud, make sure that new VMs with the runner- prefix have appeared.

Create a test scenarioCreate 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 createdDelete the resources you created

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

• GitLab instance
• VM with GitLab Runner
• Service account