github.com/ssube/gitlab-ci-multi-runner@v1.2.1-0.20160607142738-b8d1285632e6/docs/executors/virtualbox.md (about)

     1  # VirtualBox
     2  
     3  > Note: The Parallels executor works the same as the VirtualBox executor. The
     4  caching feature is currently not supported.
     5  
     6  VirtualBox allows you to use VirtualBox's virtualization to provide a clean
     7  build environment for every build. This executor supports all systems that can
     8  be run on VirtualBox. The only requirement is that the virtual machine exposes
     9  its SSH server and provide a bash-compatible shell.
    10  
    11  ---
    12  
    13  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
    14  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
    15  **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
    16  
    17  - [Overview](#overview)
    18  - [Create a new base virtual machine](#create-a-new-base-virtual-machine)
    19  - [Create a new Runner](#create-a-new-runner)
    20  - [How it works](#how-it-works)
    21  
    22  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    23  
    24  ## Overview
    25  
    26  The project's source code is checked out to: `~/builds/<namespace>/<project-name>`.
    27  
    28  Where:
    29  
    30  - `<namespace>` is the namespace where the project is stored on GitLab
    31  - `<project-name>` is the name of the project as it is stored on GitLab
    32  
    33  To overwrite the `~/builds` directory, specify the `builds_dir` option under
    34  the `[[runners]]` section in
    35  [`config.toml`](../configuration/advanced-configuration.md).
    36  
    37  ## Create a new base virtual machine
    38  
    39  1. Import or create a new virtual machine in VirtualBox
    40  1. Log into the new virtual machine
    41  1. If on Windows, install [Cygwin]
    42  1. Install the OpenSSH server
    43  1. Install all other dependencies required by your build
    44  1. Log out and shutdown the virtual machine
    45  
    46  It's completely fine to use automation tools like Vagrant to provision the
    47  virtual machine.
    48  
    49  ## Create a new Runner
    50  
    51  1. Install GitLab Runner on the host running VirtualBox
    52  1. Register a new GitLab Runner with `gitlab-ci-multi-runner register`
    53  1. Select the `virtualbox` executor
    54  1. Enter the name of the base virtual machine you created earlier (find it under
    55     the settings of the virtual machine **General > Basic > Name**)
    56  1. Enter the SSH `user` and `password` or path to `identity_file` of the
    57     virtual machine
    58  
    59  ## How it works
    60  
    61  When a new build is started:
    62  
    63  1. A unique name for the virtual machine is generated: `runner-<short-token>-concurrent-<id>`
    64  1. The virtual machine is cloned if it doesn't exist
    65  1. The port forward rules are created to access the SSH server
    66  1. The Runner starts or restores the snapshot of the virtual machine
    67  1. The Runner waits for the SSH server to become accessible
    68  1. The Runner creates a snapshot of the running virtual machine (this is done
    69     to speed up any next builds)
    70  1. The Runner connects to the virtual machine and executes a build
    71  1. The Runner stops or shutdowns the virtual machine
    72  
    73  [cygwin]: https://cygwin.com/