How Do I Setup Automatic Deployments With GitLab?

Disclaimer: This tutorial uses a fresh Ubuntu 18.x Droplet on DigitalOcean. However, this guide is fairly general and will likely aid you regardless of having your server hosted on DigitalOcean.

If you've ever had an interest in setting up automatic or semi-automatic deployments via GitLab I have good news for you, the process is much simpler than it may first seem. Before we get started, this guide assumes your deployments can be performed via simple shell commands and that you are utilizing some sort of version control software. In my case, I will be using git to demonstrate this functionality.

Installing the GitLab Runner

First things first, install the gitlab-runner on your remote server that you intend to deploy your application to. The steps vary depending on the operating system you are using. For this example I will be using Ubuntu 18.x. The gitlab-runner will be responsible for running our commands on the remote server and will respond to jobs generated by our GitLab pipelines. Below are the commands to quickly install the gitlab-runner in a linux environment. Be sure to select shell when prompted for the type of runner you would like to use.

$ curl -LJO https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb
$ dpkg -i gitlab-runner_amd64.deb
$ sudo gitlab-runner register
$ sudo gitlab-runner start

Creating an Environment in GitLab

Next we will create a new environment in GitLab. To do so go to Environments > New and enter the name you want to use for your remote server.

Configuring .gitlab-ci.yml

Now let's create a project (repository) in GitLab and create our .gitlab-ci.yml file. The .gitlab-ci.yml file contains all of the instructions for our pipelines in GitLab and from this file we can configure our deployments. Below we specify the environment and add the when: manual configuration so that we can manually trigger our deployments.

stages:
  - deploy

deploy_staging:
  stage: deploy
  script:
    - cd /var/www/yoursite/html && ls -al && git pull origin
  environment:
    name: testenvironment
    url: https://yourdomain.tld
  only:
    - master
  when:
    - manual

Setting Up Permissions

This step may not be necessary dependent on your setup and your needs — i.e. if you intend to use git outside of your automated deployments.

Modify permissions on the .git folder to be those you want. Add your gitlab-runner user to whatever group owns the directory you need to git pull from:

$ sudo chown -R .git desired-user:desired-group
$ sudo usermod -a -G group gitlab-runner
$ groups gitlab-runner

Triggering Your First Deployment

At this point you should make a commit and push to your GitLab instance. After pushing you should see a play button indicating that manual steps can be triggered. Go ahead and click the play button to trigger the deployment. It's worth viewing the task in the pipeline so that if any errors are encountered you can correct them via SSH on your remote server.

For instance, if you encounter error: unable to unlink old 'filename': Permission denied then you need to give the group write access:

$ sudo chmod -R g+w /var/www/yoursite/html

Next, I would recommend setting up a read only deployment key for your runner. You can do this by navigating to your project's Settings > Repository > Deploy Keys.