====== GitLab-Runner ======

//Documentation at https://docs.gitlab.com/ee/ci/runners/ //

In GitLab CI/CD, Runners run the code defined in .gitlab-ci.yml. They are isolated (virtual) machines that pick up jobs through the coordinator API of GitLab CI/CD.

A Runner can be specific to a certain project or serve any project in GitLab CI/CD. A Runner that serves all projects is called a shared Runner.

Ideally, the GitLab Runner should not be installed on the same machine as GitLab. Read the requirements documentation for more information.


===== Executor =====

//Documentation at https://docs.gitlab.com/runner/executors/README.html //

<WRAP left round info 99%>
More info on Windows shells: \\
[[kb:common:shell|Shells]]
</WRAP>


The Windows batch shell (commonly referred to as cmd, cmd.exe or the command prompt) has reached the End of Life stage regarding GitLab support. It continues to work, but will receive no updates. A change to Powershell is highly recommended!

Powershell is the modern Windows command prompt. Usage is similar to cmd, but with a few key differences. Some UNIX commands are also supported, such as ''ls''.

GitLab-related Powershell specific details:
  * environment variables set by GitLab CI can be used with just a ''$'' prefix, however, system set environment variables must have a ''$env:'' prefix. For simplicity's sake, it is best to use ''$env:'' everywhere. (sometimes, variables must also be enclosed by quotation marks to properly function, see the [[https://docs.gitlab.com/ee/ci/variables/#powershell|GitLab Docs]])
  *''out-null'' is the Powershell variant of NUl or /dev/null
  * to call a cmd script from Powershell use: ''cmd /c "insert script or command here"''


=== Migrating from Batch to Powershell ===

A freshly installed GitLab Runner will already be designed to work in Powershell. If one is upgrading a Runner based on cmd, a ''shell = "powershell"'' line has to be inserted after the ''executor = "shell"'' line.

<WRAP center round tip 99%>
As of August 2022, the registration script will create a line in the //config.toml// file reading ''shell = pwrs'' which does not run correctly in Windows. You have to modify that line to read ''shell = powershell'' ([[https://stackoverflow.com/questions/68109273/exec-pwsh-executable-file-not-found-in-path|source]]). 
</WRAP>

Unfortunately, there is no panacea for the migration of the scripts. Each cmd script must be individually migrated to Powershell. Be sure to look through the code and see if it is in accordance with the above-mentioned specifics. Other issues may arise, these probably will have to be handled on a trial-and-error basis.

**Regular Expression:** Most important are the variable names. To change the enclosing ''%'' characters to ''$env:'', one may use Regular Expressions. The RegEx ''[%](?!\s)((?:(?![%]).)*)(?<!\s)[%]'' captures any code snippet which starts and ends with a ''%'' sign, does not contain a whitespace character before or after the ''%'' signs and doesn't have a ''%'' sign anywhere in the middle. This correctly identifies the variables that need to be changed. The replacement RegEx is ''$env:$1'', this inserts the required prefix before every variable name. For more detailed information and to test the RegEx, use the site www.regex101.com. IDEs and/or Text Editors handle escape characters in different ways, e.g. one might need to change the ''[%]''s to ''\%''.