GitLab : Quickstart

GitLab is a git repository management tool, like GitHub or BitBucket. Like them, it offers issue tracking and wikis. However, GitLab also offers some very powerful features like Continuous Integration (CI) and Continuous Delivery (CD).

In this post we will cover the main features, to provide you with a quickstart!

Project and repository

This is the main view of a project. It allows to browse and modify the different files of the project. Just like GitHub, the README file is rendered to display an overview of the project.

The Repository menu (on the left) allows to browse the commits and branches of the project, and also to display them as a graph.

Issue tracking

The issue tracking system is simple classical.

Issues can be closed directly by committing to the git repository, with a commit message like "Fixes issue #1". By default, all keywords like Fixes, Fix, Closes, Resolves and Implements can be used.

Automatic issue closing documentation on GitLab

GitLab also has a Board view of issues, which allows to use the SCRUM methodology for managing the project.

Continuous Integration (CI)

This is one of the main strengths of GitLab: it has a Continuous Integration engine that runs tests each time commits are pushed to the repository. This is a like a built-in travis-ci or Jenkins!

The tests are actually called jobs. These jobs are usually executed by workers using docker containers, but other tools can also be used, like VirtualBox images.

A single execution of all the jobs defined in a project is called a pipeline.

The jobs that have to be executed are defined in a file called .gitlab-ci.yml located at the root of the project. Typically, this file defines:

• the different commands that have to be executed : script
• the docker image that has to be used: image
• the different configuration commands that have to be run before executing the job: before_script

Usually, the different options like image or before_script can be defined separately for each job, or globally for the complete pipeline.

Here is a simple example:

image: alpine:latest

test:
  before_script:
    - apk update && apk add bash
  script:
    - /bin/bash echo.sh

The test job will fail if the script command returns anything but 0.

Jobs can also be executed in parallel using stages. The configuration below defines 3 stages. These stages will be executed sequentially, but job2 and job3 will be executed in parallel.

image: alpine:latest

stages:
  - build
  - test
  - deploy

before_script:
  - apk update && apk add bash

job1:
  stage: build
  script:
    - /bin/sh echo.sh

job2:
  stage: test
  script:
    - /bin/sh echo.sh

job3:
  stage: test
  script:
    - /bin/sh echo.sh

job4:
  stage: deploy
  script:
    - /bin/sh echo.sh

GitLab even provides a visual representation of the different stages and jobs in the details of the pipeline:

.gitlab-ci.yml documentation on GitLab

PHP

This is a typical .gitlab-ci.yml for a PHP project

# https://hub.docker.com/_/php/
image: php:5.6

before_script:
  # Install git, the php image doesn't have installed
  - apt-get update -yqq
  - apt-get install git -yqq
  # Install mysql driver
  - docker-php-ext-install pdo_mysql
  # Install composer
  - curl -sS https://getcomposer.org/installer | php
  # Install PHP-ZIP extension (used by composer)
  - apt-get install -yqq libzip-dev
  - docker-php-ext-install zip
  # Install xdebug extension (used for phpunit code coverage)
  - pecl install xdebug
  - docker-php-ext-enable xdebug
  # Install all project dependencies
  - php composer.phar install

services:
  # https://hub.docker.com/_/mysql/
  - mysql

variables:
  # Configure mysql service
  MYSQL_DATABASE: hello_world_test
  MYSQL_ROOT_PASSWORD: mysql

# Test with PHP5.6 (the default)
test:php56:
  script:
    - vendor/bin/phpunit --coverage-text

# Test with PHP7.2 
test:php72:
  image: php:7.2
  script:
    - vendor/bin/phpunit --coverage-text

To speed-up your tests, you can use a docker image that already has all required tools and extensions installed:

before_script:
  # Install all project dependencies
  - composer install

services:
  # https://hub.docker.com/_/mysql/
  - mysql

variables:
  # Configure mysql service
  MYSQL_DATABASE: hello_world_test
  MYSQL_ROOT_PASSWORD: mysql

# Test with PHP7.2 
test:php72:
  image: cylab/php72
  script:
    - vendor/bin/phpunit --coverage-text

Java/Maven

Here is a simple example .gitlab-ci.yml for a java/maven project:

image: maven:3-jdk-8

mvn:package:
  script: mvn clean package

Badges

GitLab has a built-in badges generator to easily display the status of your pipeline and the current code coverage of the tests in your project. You can find it under Settings > CI/CD > General pipelines settings

Integration

GitLab can be easily integrated with external tools using webhooks, services, deploy keys and pushing to a remote repository.

Webhooks allow to trigger an action when commits are pushed to the repository by performing a HTTP POST request to a predefined URL. You can configure webhooks under Settings > Integrations.

Services are plugins built in GitLab to trigger actions in different external tools like Slack, Packagist, Bugzila, JIRA and many other. You will find them under Settings > Integrations as well.

Deploy keys will allow external tools to access your private repository. You will find them under Settings > Repository.

The pushing to remote repository feature allows, as the name states, to propagate modifications from the GitLab repository to an external GIT repository. This is useful for to clone your repository on GitHub, for example.

Contiunous Deployment : Auto DevOps

If you are using Docker and Kubernetes to run your production apps, GitLab can automatically build, upload, deploy and configure your containers, and monitor the state of your running containers. This allows to centrally manage the complete development and deployment process.

This will be covered in another blog post...

This blog post is licensed under CC BY-SA 4.0