Deploying GitLab Runner on a Compute Cloud virtual machine

GitLab Runner is an open-source application that executes GitLab CI/CD pipeline jobs based on instructions from a special file named .gitlab-ci.yml. You can deploy GitLab Runner either in a Yandex Managed Service for Kubernetes cluster or a Compute Cloud virtual machine, which is an easier and cheaper option.

Compute Cloud offers two ways to work with GitLab Runner: You can:

• Create a VM and install GitLab Runner on it manually.
• Using the management console, create a runner that will automatically deploy the specified number of VMs ready to run jobs.

To get started with GitLab Runner using Compute Cloud:

1. Set up your infrastructure.
2. Get a GitLab Runner token.
3. Install the GitLab Runner agent on the Yandex Compute Cloud VM or create a runner using the management console.
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 throughout the GitLab instance (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 configure GitLab Runner project settings:

  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.

Install GitLab Runner on a Yandex Compute Cloud VMInstall GitLab Runner on a Yandex Compute Cloud VM

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

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 may 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. 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 Scaling settings, specify:

   • Maximum number of workers
   • Minimum number of workers
   • Worker downtime limit in minutes
   • Maximum number of jobs per worker
   • Maximum number of parallel jobs per worker

9. Optionally, add labels for the worker.

10. Under Computing resources, select one of the preset configurations.

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

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

12. Click Create VM.

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