How to install Gitlab CE and Vagrant on macOS

Written by me@grafxflow

22 Apr, 2020



How to install GitLab CE with Vagrant on macOS

In this tutorial you will be able to install GitLab Community Edition locally on your mac using a vagrant box. This tutorial has been tested with macOS 10.15 and at the time of writing this tutorial, the latest version of GitLab CE is 12.9.3 and the latest version of Ubuntu is 18.04 (bionic64).


First you must make sure all the following are installed.

  1. Vagrant - download
  2. Virtual Box - download
  3. Github Desktop (Optional for section 8) - download

NOTE: Ruby versions 2.0 and above are included by default in macOS releases since at least El Capitan (10.11).

You should already have ruby installed so lets check this first.

ruby -v


/usr/bin/ruby -v

This should output something like.

ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin19]

1. Create the vagrant file

At first in the terminal make the directory that will be used for the GitLab CE installation and set it as default, so for this example 'gitlab-local'.

mkdir gitlab-local

cd /gitlab-local

Then create a vagrant file.

vagrant init

Now open this file.

vim Vagrantfile

And replace the content with the following - you may need to change the forwarded_port and private_network to your own settings.

# -*- mode: ruby -*-
# vi: set ft=ruby :


Vagrant.configure(VAGRANTFILE_API_VERSION) do |config| = "ubuntu/bionic64"
  config.vm.hostname = "gitlab.local"

  if Vagrant.has_plugin?("vagrant-vbguest")
    config.vbguest.auto_update = false
  end "forwarded_port", guest: 80, host: 8080 "forwarded_port", guest: 22, host: 8022 "private_network", ip: ""
  config.vm.synced_folder ".", "/vagrant", type: "rsync", rsync__exclude: [".git/"]

  config.vm.provider "virtualbox" do |vb|
    # Display the VirtualBox GUI when booting the machine
    #vb.gui = true = "gitlab.local"
    # Customize the amount of memory on the VM:
    vb.memory = "4096"

  config.vm.provision "shell", inline: <<-SHELL
    sudo apt-get update
    sudo apt-get install -y curl openssh-server ca-certificates

    debconf-set-selections <<< "postfix postfix/mailname string $HOSTNAME"
    debconf-set-selections <<< "postfix postfix/main_mailer_type string 'Internet Site'"
    DEBIAN_FRONTEND=noninteractive sudo apt-get install -y postfix

    if [ ! -e /vagrant/ubuntu-bionic-gitlab-ce_12.9.3-ce.0_amd64.deb ]; then
        wget --content-disposition -O /vagrant/ubuntu-bionic-gitlab-ce_12.9.3-ce.0_amd64.deb
    sudo dpkg -i /vagrant/ubuntu-bionic-gitlab-ce_12.9.3-ce.0_amd64.deb
    sudo gitlab-ctl reconfigure

Now startup the vagrant box, this will initially take a while to install all the required files such as Gitlab CE.

vagrant up

Change the host file to recognise http://gitlab.local in your browser by opening the following which should also ask for your password.

sudo vim /private/etc/hosts

Then add the following line at the bottom and save it. gitlab.local

2. Change the default hosting url ( for Gitlab CE

Access the Ubuntu terminal of the virtual box.

vagrant ssh

Now in the same terminal window edit the following file.

sudo vim /etc/gitlab/gitlab.rb

And find and replace.

external_url ''


external_url 'http://gitlab.local'

Then enter the following for the change to take effect.

sudo gitlab-ctl reconfigure

3. Login to GitLab CE dashboard and change your user details

Open your browser with url http://gitlab.local. The first time around it will ask you to change your password.

Install Gitlab CE screen 1

Once done it will redirect you to the login page. By default the username is root so just enter this and your new password.

Install Gitlab CE screen 2

Now you should have access to the Gitlab CE Dashboard.

Install Gitlab CE screen 3

4. Edit the user account

First thing you should do is change your user details, so choose Settings and change your 'Email' and 'Full name' then press the 'Update profile settings' button.

Install Gitlab CE screen 4

You will receive an email just to confirm that it's exists. If the external_url has worked correctly the link in the email will work fine.

And then edit your username by selecting Account.

Install Gitlab CE screen 5

5. Create new repo

Create a new project so for this example I have used first-project.

Install Gitlab CE screen 6

You will be asked to first generate a SSH key.

Install Gitlab CE screen 7

6. Generate a new SSH key

Open a new terminal window and enter the following.

ssh-keygen -t rsa -C ""

Then enter the filename you want the key to be named, just press return if you want to keep the default generated name but I would suggest using a custom name and remember to include the full directory in the filename like below.


Now just press enter twice to keep the passphrase empty.

Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 

Open the public key with your naming above.

vim /Users/[username]/.ssh/

You will have a line of random code begining with 'ssh-rsa' so copy this for use with GitLab.

Go back to the GitLab CE dashboard and press the Add SSH Key and paste the public key then press Add key.

Install Gitlab CE screen 8

You should get an email to confirm this.

7. Access the new repo via the terminal (or with the 'GitHub Desktop app' see section 8)

First open the following file and link your ip/url to your key.

vim /Users/[username]/.ssh/config

And add the following.

Host gitlab.local
HostName gitlab.local
User your-gitlab-name
Port 22
IdentitiesOnly yes
IdentityFile /Users/[username]/.ssh/id_gitlab_ce_rsa

So now you can clone the repo by entering this in the terminal.

mkdir gitlab-local-repos

cd /gitlab-local-repos

git clone git@gitlab.local:your-gitlab-name/first-project.git

It will initially ask you the below, so just enter 'yes'.

Are you sure you want to continue connecting (yes/no/[fingerprint])? 

This should be working fine.

8. Access the new repo with the GitHub Desktop app

With the Github Desktop application things work a little different regarding accessing your repos. So lets start by selecting Settings then Access Tokens on the left navigation.

Install Gitlab CE screen 9

At first enter a name - so for this example 'First Project' and select the api checkbox. Then press the 'Create personal access token' button.

Install Gitlab CE screen 10

The page should refresh and generate a code under Your New Personal Access Token. Make sure to get a copy of this code because we will need to use this in the Github Desktop application.

Install Gitlab CE screen 11

Now select the 'Your Gitlab Name / first-project' repo.

Install Gitlab CE screen 12

On the following page choose the Clone dropdown button and highlight either the http or https that appears so for example.


Install Gitlab CE screen 13

Now launch the GitHub Desktop app and choose 'Clone a Repository from the Internet...'.

Install Gitlab CE screen 14

Input the repo url and the destination folder.

Install Gitlab CE screen 15

Now the first time doing this you will be asked for the Authentication Login so add your username (for this example 'Your Gitlab Name') which you used to access the GitLab dashboard and the password which should be the generated 'Personal Access Token'.

Install Gitlab CE screen 16

Now you should get the cloning progress bar and it will have synced the repo of your local GitLab CE.

Install Gitlab CE screen 17

I hope this has been helpful.

Add comment

Smart Search

132 Following


Hull, United Kingdom

I am a Full-stack Developer who also started delving into the world of UX/UI Design a few years back. I blog and tweet to hopefully share a little bit of knowledge that can help others around the web. Thanks for stopping by!