In part 1, and part 2 of this series, we covered the installation and configuration of pre-requistites, setting up our GitLab account and initial settings, and finally getting our Windows Runner installed and operational.
Today’s, I’ll give an overview of how GitLab uses build configuration files, how it is constructed, and setup our project in preparation for getting our first build complete.
GitLab Build Conifiguration
Previously, I’d been using Jenkin’s for my CI system, and immediately noticed how build configuration is different. With GitLab CI, the build file itself, .gitlab-ci.yml, is actually part of the repository. No webhook setup is necessary.
We also now have capabilities, such as not only having a dedicated runner per project, but per branch of our project, which we can control and manage directly from our repo.
Create a Demo PowerShell Script
Let’s setup a really simple script which we want to pass through the CI Engine.
- Log back into the GitLab environment
- Open your project
Now launch the PowerShell ISE, and make the following script:
$x = 'Hello' $y = 'Word' $strHellowWorld = "$x $y" Write-Output $strHellowWorld
Save the file as HelloWorld.ps1 into the root of your repository (C:\temp\helloworld in my case)
Commit and Push to GitLab
We’ve added content to the repository, so lets go ahead and push the changes to GitLab.
- Start a Bash session
- Set your current current directory to the root of your repository
- Enter the commands below
git add HelloWorld.ps1 git commit -m "Created initial HelloWorld script" git push origin master
Now return to GitLab, and select Commits to confirm the commit has occurred.
To the right of the commit, you will see a red ‘x’ mark. You might think that this is an options to delete the commit that has been made, but it’s something else entirely.
Click on the red cross. Looking further down the screen we see an error message.
Found errors in your .gitlab-ci.yml:
Undefined yaml error
.gitlab-ci.yml not found in this commit
As mentioned, .gitlab-ci.yml is the build file that stored within the repository itself. The commit has been successfully placed into source control, but because we enabled CI for this project, GitLab has also expected the build file to exist.
A Quick bit About YAML and gitlab-ci.yml
We’re now at the stage where we are wanting to design our build configuration file for the helloworld project.
Build actions for GitLab projects are stored within a file, .gitlab-ci.yml, which is placed in the root of a repository. This file uses YAML format, and describes the build actions and criteria. Those of you familiar with AppVeyor may be aware of this format of file, and the requirements it has to be successfully parsed.
You can read more about YAML on WikiPedia, and other sources.
As a newbie I struggled with this file, and it took me a whole day before I was able to get a successful build to occur (though it wasn’t helped by my build script being quite longer than our example). I’ll cover this file in a bit more detail, and the gotchas I’ve come across in a later blog. But for now, we’ll make a basic build file.
Building our gitlab-ci.yml file
Launch Notepad, and paste the following text into it:
ps_helloworld: script: - .\HelloWorld.ps1 | Out-File c:\windows\temp\helloworld.txt tags: - windows
Our configuration file consists of a label at the top, which identifies the name of the build, the script to be executed, and uses a tag of ‘Windows’ to identify the Runner to be used.
You might be wondering why I placed :
| Out-File c:\windows\temp\helloworld.txt
in the build script instead of directly into the PowerShell script. The reason for this is simply to demonstrate how we can actually use PowerShell within our build script, and not just call PowerShell scripts.
- Save the file as .gitlab-ci.yml within the repository, and return to Bash.
- Add, commmit, and push this file to GitLab.
Let’s take a look at the status of this build from GitLab. What’s particularly interesting here is that the actual command within the the script section of the build file is displayed. More about that later….
So our build has reported as being successfully, and if we take a look at C:\Windows\Temp on our build server, the file is there. Our first experience with GitLab CI is complete! 🙂
The next article in the series will cover some difficulties i’ve had getting to grips with GitLab CI, and how I was able to go from this :
Thanks for reading. Comments, errors and any feedback always welcome.