Introduction

During the last article in this series on the use of PowerShell with GitLab, we noticed some displays on the build console, and some results from our build that was a bit unusual.

Today, I’m going to look a bit further into how the build engine works, which will also explain some of these results we are seeing.

How GitLab CI Runner Works

It would be logical to think that the PowerShell code is run in the same location or a subdirectory of the folder where the service file is, similar to Jenkins, but after a bit of investigation, I found out this is not the case.

To look further into what was happening, let’s add a line to the script section of the YAML file, and put a Start-Sleep command in.Make it ten minutes, to give enough time to remote onto the GitLab CI Runner, and do a search for our .ps1 file stored in a subdirectory of the repository.

Use the content below for our build file.

ps_helloworld:
  script:
         - function HappyHelloWorld {
         -    $x = "Hello world"
         -    Write-Output "I would just like to say $x"
            }

         - HappyHelloWorld | Out-File 'c:\windows\temp\helloworld.txt'
         - Start-Sleep -Seconds 600
  tags:
        - windows

• Save the changes
• Add the updated file
• Commit the changes
• Push the changes
• Navigate to the build section
• Click on the commit

The job is running, and because of the Start-Sleep command, will continue to do so for the next ten minutes.

Discoveries

• Remote onto your build server (if it is not already the same system you are accessing GitLab from.
• Go to the C:\Windows\Temp

There will be a folder name of the format Build_xxxx

• Double click on the folder

• Within this folder is a script.ps1 file.
• Open the file

The PowerShell code contained within the script: section of the YAML file is adjusted to make it suitable for returning the output we can see on the console window within a Gitlab job.

Looking at the code now, we can see that it has been changed significantly :

• ErrorActionPreference has been set to ‘Stop‘.
• Commands are in place to check to see if an error has occured, and if so to exit the script.  This will also result in the job being flagged as having failed.
• Probably the most interesting of the changes is the frequent use of Echo command which mimics the command that follows it.

This explains several things to us :

• How the console output is seen on the job screen
• Some lines output appeared strange because variables were undefined at the stage when the Echo command ran

Because PowerShell returns all output from a function, it explains why were receive an array when the HappyHelloWorld function is called. It consists of the intented output, but also the Echo commands.

The use of a function in our build code now becomes a challenge or possibly could be perceived as something to be avoided, since we cannot guarantee the element in the array that will contain our desired output.  One way i’ve been able to get round this is to make the function return a PScustomobject, and make use of the -is operator outside of the function to obtain the value.

e.g. $functionOutput = $arrayReturned | Where {$PSItem -is [pscustomobject]}

However, I’ve found a better approach is to minimize the actual PowerShell commands that you use in the script, and instead create a Build folder within your repository which contains files with the actual commands that you wish to use for the build. These can be dotsourced to make them available from within the script, without the need for adding custom code to handle this.

There are many other aspects and configuration settings possible within GitLab, which lets you have powerful control over your build steps. Examples of this are defining the order of execution, ignoring errors, and setting the steps to be taken after each one.

It’s also worthwhile noting that these articles do not include the use of testing, which should be part of your chain of operations. If you are not already familiar with the use of Pester, I’d recommend taking a look at the documentation and examples on GitLab. Amongst others, Jakub Jareš has also written an excellent series of articles on its use, which you can find on PowerShellMagazine.com

That’s it for this series of articles on the use of PowerShell and GitLab. Thanks for reading, and feel free to provide feedback.

cheers,

Tim