The GitLab CI File
This is really going to be a crash course in the .gitlab-ci.yml file – I want to start off by saying it’s super powerful. Your only limitation is your imagination, seriously. What I’m going to show you here is only a nugget of information versus what is available at the official documentation pages. Want to start the dishwasher with a commit, you could do that, given enough resources and maybe a Raspberry Pi if you’re into that.
Create the CI file
You’ll need to create a .gitlab-ci.yml file at the root of your repo, so if you’re like me and tracking only the /wp-content folder, guess where you create the file? Yep, you’ll need it at /wp-content/.gitlab-ci.yml
Ignore all the gibberish on the right, my file is a bit more complicated than what we’re going to go into, I have way more steps than you need to get started.
Selecting your Docker image
Yes you read that right, Docker – it’s a powerful container-based solution in the development world. And just so happens to be available for use on GitLab ( kudos guys for including this ).
For me, I wasn’t able to find a lightweight image and originally started using thecodingmachine/php:7.2-v2-fpm-node8 but turned out to be quite heavy ( 200MB-ish I think ) but it did include a slew of options. I’m not going to go in-depth on docker here, but to simplify, the thecodingmachine/php portion of the image is where you can find it on docker hub ( the owner if you will ) the 7.2-v2-fpm-node8 portion of the image is the ‘tag’ or ‘version’ of the image. The colon acts as a seperator, simple eh?
Since this image was quite large for what I was doing ( running a composer install and deploying afterward ) I wanted to simplify and create my own, thus the plugish/php_builder was born which now includes rsync by default so I didn’t have to reinstall it each time and node and npm.
I’ll write a post about that sometime after it’s polished I figure. For now, the one from thecodingmachine is sufficient if you don’t trust my image, it won’t hurt my feelings, I promise.
So, to start off our gitlab-ci.yml file we need to add a global image ( more on images here ) to the first line in your file ( substitute it for the other image if need be ):
# ... more things to come
Preparing for rsync deploys
Now, remember the SSH key stuff we did earlier, here’s where the fun comes in. And honestly there may be a simpler way of doing this, but this is what I’ve found works for me, so your mileage may vary.
We need to now set up a global before_script option in the yaml file. I say global, because you can do this per-job if you want to, but I prefer not to duplicate work if I don’t need to.
- eval $(ssh-agent -s)
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
- echo "$SSH_REMOTE" > ~/.ssh/known_hosts
- chmod 644 ~/.ssh/known_hosts
That’s quite a lot to take in, so let me try and break it down a bit.
eval $(ssh-agent -s) – this basically starts the client, or ensures it’s started – I’m sure there’s a more technical explination here, but this suites me very well
echo “$SSH_PRIVATE_KEY” … – this adds our private key to our SSH client. If during the configuration you’ve set the variable in GitLab to protected, the branch you’re running this on will need to be a protected branch as well, otherwise you will not be able to access the variable.
mkdir -p ~/.ssh – As the name suggests, this makes a directory called .ssh if it doesn’t already exist.
chmod 700 ~/.ssh – this ensures we can read/write to the newly created directory
echo “$SSH_REMOTE” … – This creates the known_hosts file in our docker image, this is required to tell the docker image that we trust the server we’re going to deploy to. I’ll show you in the rsync section how to ignore this if you really want to.
chmod 644 … – This ensures that the main user and other users can at least read the known hosts file we just created, nothing special here. ( No worry here, we don’t care if others read this and the container is deleted afterward, so nothing stays around sitting )
Now, for each job we run, we are guaranteed to have our ssh keys setup, great.
NOTE: If you opted to not use my Docker image, I suggest adding the following two lines to the config file ( the yml ) to ensure the ssh-agent is installed as well as rsync:
#... other stuff
- 'which ssh-agent || ( sudo apt-get update -y && sudo apt-get install openssh-client -y )'
- 'which rsync || ( sudo apt-get update -y && sudo apt-get install rsync -y )'
Phew, okay so that’s a lot to take in, huge thanks for taking it this far! Let’s jump to the final section, creating your job!
On to Page 4 now, almost there, one left after that!