github.com/nilium/gitlab-runner@v12.5.0+incompatible/docs/executors/virtualbox.md (about)

     1  # VirtualBox
     2  
     3  NOTE: **Note:**
     4  The Parallels executor works the same as the VirtualBox executor. The
     5  caching feature is currently not supported.
     6  
     7  VirtualBox allows you to use VirtualBox's virtualization to provide a clean
     8  build environment for every build. This executor supports all systems that can
     9  be run on VirtualBox. The only requirement is that the virtual machine exposes
    10  its SSH server and provide a bash-compatible shell.
    11  
    12  NOTE: **Note:**
    13  GitLab Runner will use the `git lfs` command if [Git LFS](https://git-lfs.github.com) is installed on the virtual machine.
    14  Ensure Git LFS is up-to-date on any virtual machine where GitLab Runner will run using VirtualBox executor.
    15  
    16  ## Overview
    17  
    18  The project's source code is checked out to: `~/builds/<namespace>/<project-name>`.
    19  
    20  Where:
    21  
    22  - `<namespace>` is the namespace where the project is stored on GitLab
    23  - `<project-name>` is the name of the project as it is stored on GitLab
    24  
    25  To override the `~/builds` directory, specify the `builds_dir` option under
    26  the `[[runners]]` section in
    27  [`config.toml`](../configuration/advanced-configuration.md).
    28  
    29  You can also define [custom build
    30  directories](https://docs.gitlab.com/ce/ci/yaml/README.html#custom-build-directories) per job using the
    31  `GIT_CLONE_PATH`.
    32  
    33  ## Create a new base virtual machine
    34  
    35  1. Install [VirtualBox](https://www.virtualbox.org) and if running from Windows,
    36     add VirtualBox installation folder (e.g. `C:\Program Files\Oracle\VirtualBox`)
    37     to `PATH` environment variable
    38  1. Import or create a new virtual machine in VirtualBox
    39  1. Config Network Adapter 1 as "NAT" (that's currently the only way the GitLab Runner is able to connect over ssh into the guest)
    40  1. (optional) Config another Network Adapter as "Bridged networking" to get access to the internet from the guest (for example)
    41  1. Log into the new virtual machine
    42  1. If Windows VM, see [Checklist for Windows VMs](#checklist-for-windows-vms)
    43  1. Install the OpenSSH server
    44  1. Install all other dependencies required by your build
    45  1. If you want to upload job artifacts, install `gitlab-runner` inside the VM
    46  1. Log out and shut down the virtual machine
    47  
    48  It's completely fine to use automation tools like Vagrant to provision the
    49  virtual machine.
    50  
    51  ## Create a new Runner
    52  
    53  1. Install GitLab Runner on the host running VirtualBox
    54  1. Register a new GitLab Runner with `gitlab-runner register`
    55  1. Select the `virtualbox` executor
    56  1. Enter the name of the base virtual machine you created earlier (find it under
    57     the settings of the virtual machine **General > Basic > Name**)
    58  1. Enter the SSH `user` and `password` or path to `identity_file` of the
    59     virtual machine
    60  
    61  ## How it works
    62  
    63  When a new build is started:
    64  
    65  1. A unique name for the virtual machine is generated: `runner-<short-token>-concurrent-<id>`
    66  1. The virtual machine is cloned if it doesn't exist
    67  1. The port-forwarding rules are created to access the SSH server
    68  1. The Runner starts or restores the snapshot of the virtual machine
    69  1. The Runner waits for the SSH server to become accessible
    70  1. The Runner creates a snapshot of the running virtual machine (this is done
    71     to speed up any next builds)
    72  1. The Runner connects to the virtual machine and executes a build
    73  1. If enabled, artifacts upload is done using the `gitlab-runner` binary *inside* the virtual machine.
    74  1. The Runner stops or shuts down the virtual machine
    75  
    76  ## Checklist for Windows VMs
    77  
    78  - Install [Cygwin]
    79  - Install sshd and Git from Cygwin (do not use *Git For Windows*, you will get lots of path issues!)
    80  - Install Git LFS
    81  - Configure sshd and set it up as a service (see [Cygwin wiki](https://cygwin.fandom.com/wiki/Sshd))
    82  - Create a rule for the Windows Firewall to allow incoming TCP traffic on port 22
    83  - Add the GitLab server(s) to `~/.ssh/known_hosts`
    84  - To convert paths between cygwin and windows, use the `cygpath` utility which is documented [here](https://cygwin.fandom.com/wiki/Cygpath_utility)
    85  
    86  [cygwin]: https://cygwin.com/