Update March 2020 - I’ve given written a newer more updated version of this article, check it out over here.
Gitlab provides some good documentation on getting build runners for your projects set up which can be found here. However I haven’t found a good article on setting up Gitlab CI for PHP applications yet.
This article is not going to discuss setting up shared runners on Gitlab since I felt the documentation provided by them in the link above was easy enough to follow, what this I am going to focus on is the
.gitlab-ci.yml configuration that I’m currently using in my projects to do the following:
- Run PHP CS against our code base to ensure that it conforms to PSR-2
- Run PHPUnit against our code base to ensure that our unit tests pass against different versions of PHP (5.6, 7.0, 7.1)
I’m using Gitlab CI to test (deploy in the next article) a number of Laravel applications which not only contain 3rd party packages but a number of our own internal packages hosted within our Gitlab CE instance.
There are a few of things we need to before we start:
- Make sure that both HTTPS and SSH git cloning are enabled. It seems that the runners use the HTTPS protocol to clone the projects into the docker container. This option is the default option and can be found by click on the Administration Area -> Settings Cog -> Visibility and Access Controls -> Enabled Git access protocols
- Make sure we have access to a private key portion of a user that can log into Gitlab. We usually give Gitlab our public key to authenticate us, however for this we’ll need our docker containers to act as us and therefore they’ll need a private key to authenticate with when contacting Gitlab when cloning down our project. You’ll need to add the private portion of the ssh key as a Secret Variable with the name of SSH_PRIVATE_KEY and the value of the Private key. Project -> Settings Cog -> CI / CD Pipelines -> Secret Variables
- Adding PHP Code Sniffer to our projects dev dependencies:
composer require squizlabs/php_codesniffer --dev
Lets get straight into the good stuff - 4 main files that are necessary to make my builds run that exist all within my project root:
phpunit.xml- I’m not going to cover this since Laravel ships with one
phpcs.xml- the PHP CS configuration file
.gitlab-ci.yml- the core configuration file for Gitlab CI
.gitlab-ci.sh- an additional configuration file for building our docker image
And below are their contents:
My PHP CS file is pretty simple it just enforces the PSR-2 coding standard within the
app folder of my project, but should you need to tailor your rules they can be added here too.
<description>The PSR2 coding standard.</description>
From the Gitlab link above:
This file specifies how the build environment should be set up and what commands to be executed to build, test, and deploy our project in a series of jobs that can be parallelized.
# Select a base image to start working with...
This file as described above will configure the environment and handle setting up the SSH agent. One thing to note is part way down you’ll need to change
ssh firstname.lastname@example.org to match your server name.
If you’re going to come across issues with Gitlab CI it’ll be with the SSH config in my experience. However hopefully with the preparation and scripts above you shouldn’t run into these problems.
Remember that you’ll need to add the SSH_PRIVATE_KEY Secret variable FOR EACH of your your projects - this caught me out a couple of times and hopefully should save you A LOT of time!