• Overview
• Create a new base virtual machine
• Create a new runner
• How it works
• Checklist for Windows VMs
  • Use Cygwin
  • Use native OpenSSH and PowerShell

VirtualBox

VirtualBox allows you to use VirtualBox’s virtualization to provide a clean build environment for every build. This executor supports all systems that can be run on VirtualBox. The only requirement is that the virtual machine exposes an SSH server and provides a shell compatible with Bash or PowerShell.

Overview

The project’s source code is checked out to: ~/builds/<namespace>/<project-name>.

Where:

• <namespace> is the namespace where the project is stored on GitLab
• <project-name> is the name of the project as it is stored on GitLab

To override the ~/builds directory, specify the builds_dir option under the [[runners]] section in config.toml.

You can also define custom build directories per job using the GIT_CLONE_PATH.

Create a new base virtual machine

1. Install VirtualBox.
   • If running from Windows and VirtualBox is installed at the default location (for example %PROGRAMFILES%\Oracle\VirtualBox), GitLab Runner automatically detects it. Otherwise, you must add the installation folder to the PATH environment variable of the gitlab-runner process.
2. Import or create a new virtual machine in VirtualBox
3. Configure Network Adapter 1 as “NAT” (that’s currently the only way the GitLab Runner is able to connect over SSH into the guest)
4. (optional) Configure another Network Adapter as “Bridged networking” to get access to the internet from the guest (for example)
5. Log into the new virtual machine
6. If Windows VM, see Checklist for Windows VMs
7. Install the OpenSSH server
8. Install all other dependencies required by your build
9. If you want to download or upload job artifacts, install gitlab-runner inside the VM
10. Log out and shut down the virtual machine

It’s completely fine to use automation tools like Vagrant to provision the virtual machine.

Create a new runner

1. Install GitLab Runner on the host running VirtualBox
2. Register a new runner with gitlab-runner register
3. Select the virtualbox executor
4. Enter the name of the base virtual machine you created earlier (find it under the settings of the virtual machine General > Basic > Name)
5. Enter the SSH user and password or path to identity_file of the virtual machine

How it works

When a new build is started:

1. A unique name for the virtual machine is generated: runner-<short-token>-concurrent-<id>
2. The virtual machine is cloned if it doesn’t exist
3. The port-forwarding rules are created to access the SSH server
4. GitLab Runner starts or restores the snapshot of the virtual machine
5. GitLab Runner waits for the SSH server to become accessible
6. GitLab Runner creates a snapshot of the running virtual machine (this is done to speed up any next builds)
7. GitLab Runner connects to the virtual machine and executes a build
8. If enabled, artifacts upload is done using the gitlab-runner binary inside the virtual machine.
9. GitLab Runner stops or shuts down the virtual machine

Checklist for Windows VMs

To use VirtualBox with Windows, you can install Cygwin or PowerShell.

Use Cygwin

• Install Cygwin
• Install sshd and Git from Cygwin (do not use Git for Windows, you will get lots of path issues!)
• Install Git LFS
• Configure sshd and set it up as a service (see Cygwin wiki)
• Create a rule for the Windows Firewall to allow incoming TCP traffic on port 22
• Add the GitLab server(s) to ~/.ssh/known_hosts
• To convert paths between Cygwin and Windows, use the cygpath utility

Use native OpenSSH and PowerShell

• Install PowerShell
• Install and configure OpenSSH
• Install Git for Windows

• Configure the default shell as pwsh. Update example with the correct full path:

  New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "$PSHOME\pwsh.exe" -PropertyType String -Force
  

• Add shell pwsh to config.toml