PowerShell and GitLab CI – Part 3

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

git - part 4 - 1 - login to git

Now launch the PowerShell ISE, and make the following script:

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 - part 4 - 3 - pushing our changes

Now return to GitLab, and select Commits to confirm the commit has occurred.

Results

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.

git - part 4 - gitlab commit screen

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

git - part 5 - gitlab commit and build details screen

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:

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 :

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.

Results

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….

successfulbuild

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! 🙂

helloworldfile

Coming Soon….

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 :

builds

To :

success

Thanks for reading. Comments, errors and any feedback always welcome.

cheers,

Tim

Share

PowerShell and GitLab CI – Part 2

Setting up a Windows GitLab Runner

Part 1 of this series on PowerShell and GitLab CI saw us setup our GIT client configuration, register and configure GitLab for our sample project, and then perform an initial clone of the project just created.

Todays blog covers the setup of a Gitlab Runner.

What is a GitLab Runner?

Quite simply, a GitLab Runner is an application which processes builds. On a Windows system, a GitLab Runner operates as a dedicated service.  Because it communicates with GitLab CI through an API, there is no requirement to have the Runner on the same server on which you have GitLab CI installed.  Runners can be setup on various operating systems, and additionally process multiple languages.

GitLab CI can use one or more Runners. This makes it not only handy when we are working in a heterogenuous environment, but also where we wish designated severs for our development, testing, acceptance, and production arenas.

Runners can be assigned per project, which gives us further flexibility. I find this very helpful, working in an environment with multiple untrusted forests. All I need to do is register a Runner in the respective forest, and then assign it to a project for that.

Preparation

Before we download and install the Windows Runner software, we need to get an identifier from GitLab. This will be used to associate a runner with a project.

  • Log back into GitLab
  • Click {yourname} / helloworld
  • Click Runners on the left hand pane
  • Copy the registration token in section 3 of How to setup a new project specific runner into the clipboard.

git3 - part 1

git3 - part 2

Installing and Configuring the Runner

Now we’ll actually get the runner operational on our build server.

  • Move gitlab-ci-multi-runner-windowsd-amd64.exe to a suitable directory. Note that this will be the directory from which the service runs. As this is a demo, I am going to place it in the Temp folder of my C: drive.

git3 - part 3

  • Start PowerShell as an administrator
  • Use Set-Location to set the current directory to the location of the file mentioned above
  • Use the command below to launch the configuration utility

You’ll now be prompted for input some information

  • coordinator URL : https://ci.gitlab.com
  • token : <paste the registration token you copied to the clipboard>
  • description : hellowworldrunner
  • tags : windows
  • executor : shell

Coordinator URL refers to the location that the runner looks to for communication with GitLabCI, Token the unique identifier that is used to identify your runner. Tags allow you to control when a job does or doesn’t build on a runner, and the executor refers to the type of script it will process.

  • If you are prompted for your current password, enter this as well.

git3 - part 4

  • Launch services
  • Find the service with the name of gitlab-runner

git3 - part 5

Note is the service is registered to run in the current context of your account.

Unless you have any specific need to keep the gitlab-runner service running in this context, carry out the following:

  • Stop the service
  • Change the Log On as: setting to the account you want it to run under. (In my case, I just set it to Local System Account.)
  • Start the service

git3 - part 6

That’s the Runner setup, and ready to be used, but first took a look at the location where the process runs from.

You should see a file there new called config.toml. This file contains the configuration settings that the Runner uses. It’s plain text, so you can open it in Notepad. It details the number of concurrent runners, the url of the gitlab cim, the token we used earlier for registration, name of the runnier, and other configuration data.

Now return to GitLab, and the Runners section we were just on, and press F5 to refresh the screen.

The helloworld runner should now be registered for this project!

git3 - part 7

In part 3 of this series, we’ll create our first GitLab CI build file, which will run a basic PowerShell script.

Share

PowerShell and GitLab CI – Part 1

GitLab 8 adds built in CI as an option, making a single instance of GitLab not only for use as a version control system, but also a continuous integration solution. GitLab is available for both use over the internet, and also locally hosted. These posts will cover the use of the internet service.

The next few posts will detail how I set this up for use with PowerShell, tested it, and some of the gotchas I came across. Todays one will cover the pre-requisites I needed to setup, and initial configuration for a new project.

Git Client

Naturally, in order to perform our GIT operations we’ll need some type of client installed. Some options available are :

NB At the point of writing this articule Posh-Git is included in the Github Desktop client, which may give you the best of both worlds.

My choice of client at the moment is Git for Windows and using the Bash CLI. I’ve still to take a proper look at Posh-Git, but it’s in the pipeline….

SSH Keys

Using the Bash console, you can create a set of SSH keys, which are going to be used later. Starting a Bash session with Git for Windows can be done by right clicking within any Explorer window, and selecting Git Bash Here

Opening a Bash session

Opening a Bash session

With the session open, type the following :

Creating the SSH keys

Creating the SSH keys

This creates a public and private key. If you accept the defaults, a folder called .ssh will be created in the root of your user profile. Within this, you will find two files, id_rsa.pub and id_rsa. The first of these will be used later when we are creating a test repository.

Register with GitLab

  • Browse to https://gitlab.com/users/sign_in
  • Follow the on-screen instructions to register
  • Open the .pub public key file created earlier, and copy it into the clipboard
  • Login to Gitlab

Step 3 - Initial Login After Registering

  • Click Profile Settings
  • Click SSH Keys.
  • Click ADD SSH KEY
  • Paste your public key into the Key box
  • In the Name box enter a descriptive name of your choice
  • Click ADD KEY.

Step 4 - Adding SSH Keys

  • Click Back to dashboard

Creating the Project

On this screen, we can import existing projects from other sources, such as GitHub, but for now, we’ll create a new one.

  • Click + NEW PROJECT
  • Enter HelloWorld into the Project path box
  • If you wish, enter text describing the project in the Description box
  • Click CREATE PROJECT

Step 5 - Create New Project

This will then take us to the project page of HelloWorld. If you further scroll down the page, commands for us to setup our repository locally are detailed.

Step 6 - Project Page

Now startup a BASH session, and change to a directory where you want to create this sample repository. Use the commands provided in the above, from  Create a new repository.

The first time that you perform the GIT CLONE command, you will be prompted if you trust the authenticity of the host, gitlab.com. Enter Yes. This information will then be recorded in a known_hosts file, which is placed within the .ssh folder referred to previously.

Once complete, close your BASH session.

Step 7 - Creating the repository

With the project created, and the repository locally cloned, we’ll go into the projects settings and enable the CI options.

  • Click Settings
  • Click Services

Step 8 - Configure Gitlab CI

  • Click Gitlab CI
  • Check Active
  • Click SAVE

When you do this, a green circle will appear next to GitLab CI on the right. New options will also appear on the left side, including Runners, CI Web Hooks, CI Settings, CI Services, and CI Events.

Step 9 - Enable Gitlab CI

  • Click CI Services
  • Click Mail

The Mail option is used to send an email when a build process has completed. Mail is enabled by default, but only for builds that do not succeed. I find it handy to have this enabled for all builds. If you wish to do this.

  • Select the Notify check box
  • Click to clear the Notify check box.
  • Click SAVE.

Step 10 - Enable Mail

That’s it for day 1. In the next article in this series we’ll deploy and configure a Windows Runner, and take a look at the options available.

Share