GitとCI/CDに関する知識ゼロのSEが、Windows OSにGitLabのRunnerを入れてCI/CDパイプラインでPowerShellコマンドを試すだけ

皆様こんにちは。SEの小池と申します。

少し前にコンテナでRunner (Type : Docker) を起動する手順 (こちら) を記載致しました。
今回はこれに関連し、Windows OSにGitLabのRunner (Type : Shell) をインストール・登録し、CI/CDパイプラインでPowerShellコマンドを試行します。

本記事の対象の方
今回のブログのゴール
このブログをお読みいただくにあたっての事前ご連絡事項
全体の流れと注意事項
Step1 : 作業前の確認
Step2 : 事前作業
Step3 : Runnerの登録
Step4 : Runnerのインストール (サービス登録)
Step5 : Runnerの開始
Step6 : CI/CDパイプラインでPowerShellコマンドを試行
【おまけ】エラーが出ちゃったときの対応
最後に

本記事の対象の方

GitLabのCI/CDパイプラインでPowerShellコマンドを使いたい方。
Windows OSにRunner (Type : Shell) をインストールしたい方。

今回のブログのゴール

このブログのゴールはこちらです。

今回のゴール

Windows OSにGitLabのRunnerを導入し、GitLabに登録する。
CI/CDパイプラインでPowerShellコマンドを試行する。

このブログをお読みいただくにあたっての事前ご連絡事項

本記事はWindows Server 2019にRunner15.0.0をタイプshellで登録します。これ以外のOS、Runnerバージョン、タイプの登録については言及しておりません。
本記事ではGitLabにおけるRunnerとは何かについては言及しておりません。これについてはこちらのブログをご参照ください。
本記事はオンプレミス版のGitLab Enterprise Edition 14.10.4-ee (Ultimate) における仕様をベースに記載しております。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
本記事のGitLabのGUIは日本語にローカライズした状態で掲載しております。それ以外の言語をご利用の方は適宜読み替えてください。
本記事はGitやCI/CDに関する知識ゼロのSEによるなんちゃって記事です。GitLabのディープな使用法についてはGitLabの公式オンラインドキュメント (こちら) をご参照ください。

全体の流れと注意事項

この記事で実施する作業では、Windows Server 2019にGitLabのRunner 15.0.0 をインストールし、タイプは Shell 、デフォルトシェルは pwsh で登録します。
登録した後、空のプロジェクトとテスト用のCI/CDパイプラインを作成し、そこで今回登録したRunnerを用いてPowerShellコマンドを実行できることまでを確認します。

全体の作業の流れは以下の通りです。

作業前の確認
事前作業
Runnerの登録
Runnerのインストール (サービス登録)
Runnerの開始
CI/CDパイプラインでPowerShellコマンドを試行

事前作業の一部、Runnerの登録、インストール (サービス登録)、サービス開始は基本的にGitLab Docsに記載の手順に従います。
参考 : Install GitLab Runner on Windows | GitLab

GitLab Docsと表記を合わせるため便宜上「Runnerのインストール」という表現を用いておりますが、この「Runnerのインストール」ではWindows OSにサービスとして登録する作業を実施しています。
インストールウィザード等、Windows OSによくあるインストール作業のようなものは特にありません。

Windows OS向けのRunnerで Shell 以外のタイプで登録したり、pwsh 以外のデフォルトシェルを指定することも可能ですが、それらの手順については本記事では言及しておりません。
他のタイプをお使いになりたい場合は、GitLab Docsをご参照の上作業をなさってください。

2022/06/10現在、PowerShell CoreはWindows OS以外のOSにインストールすることができます。
しかしこの記事では、Windows以外のOSにPowerShell Coreをインストールして、それをCI/CDパイプラインから実行する場合については検証しておりません。
参考 : GitHub - PowerShell/PowerShell: PowerShell for every system!

また、次章で詳細を記載致しますが、Windows OS向けの Runner はバージョンによってデフォルトの shell が異なります。
バージョン12.0から13.12のRunnerはデフォルトのシェルがpowershell、14.0以降はデフォルトのシェルがpwshです。
このブログではRunner15.0.0を用いるためデフォルトシェルはpwshですが、実際に業務でWindows OSのRunnerを用いる場合は、事前にCI/CDパイプラインで実行する処理やコマンドの内容を確認した上で、Runnerで使用するデフォルトのシェルを設定してください。
参考 : Types of shells supported by GitLab Runner - Overview | GitLab

Step1 : 作業前の確認

事前にCI/CDパイプラインで実行する処理やコマンドの内容を確認し、デフォルトのシェルを何にするのかをご検討ください。
これは、Runnerのバージョンによってデフォルトのシェルが異なるためです。

Runnerバージョン12.0から13.12のRunnerはデフォルトのシェルがpowershell、14.0以降はデフォルトのシェルがpwshです。
利用するシェル設定がpowershellの場合、コマンドはPowerSehll Desktopで実行されるとあります。

All commands are executed in PowerShell Desktop context.

出典 : Types of shells supported by GitLab Runner - Overview | GitLab

一方、利用するシェル設定がpwshの場合、コマンドはPowerShell Coreで実行されるとあります。

All commands are executed in PowerShell Core context.

出典 : Types of shells supported by GitLab Runner - Overview | GitLab

CI/CDパイプラインで実行する処理によっては、このデフォルトのシェルの設定を変える必要があります。

また、検討して決定したデフォルトのシェルがそもそもWindows OS側で利用可能かを、Runnerをインストールする前にご確認ください。
PowerShell Coreがない状態のWindows OSにRunner15.0.0を入れ、そのままCI/CDパイプラインをまわし、思いっきり「pwshのパスないんだけど」というエラーが出たのは私です。

Step2 : 事前作業

今回はRunner15.0.0を、デフォルトシェルpwshのまま使います。
ですので、Windows OS側にPowerShell Coreがインストール済み且つ pwshにパスが通っているかを確認します。

コマンドプロンプトからpwshと実行することで、PowerShell Coreがインストール済か否かを確認できます。
PowerShell Coreがインストール済であれば、そのままプロンプトの行頭にPSと表示され、PowerShellコマンドを利用可能になります。

PowerShell Coreが未インストールであれば、pwshがコマンドとして認識されない旨が表示されます。

次に、GitLb Docsの指示に従いGitをインストールします。
Windows OS向けのGitはこちらの公式サイトから入手可能です。
参考 : Install GitLab Runner on Windows | GitLab、Git - Downloading Package

次に、Runnerのサービスを Local System 以外の任意のユーザーで実行したい場合に限り、そのユーザーを事前に作成しておきます。
(Runnerサービスはデフォルトでは Local System で実行されますが、これを変更することが可能です。)

最後に、GitLabでローカルCAで発行した証明書を利用している場合は、ルートCAの証明書を用意します。

以上で事前作業は完了です。

Step3 : Runnerの登録

Runnerを登録します。
参考 : Install GitLab Runner on Windows | GitLab

まず、Runnerの本体を格納するフォルダーを作成します。
ここではC:\GitLab-Runner\として作業を進めます。

次にRunner本体をダウンロードします。
該当するものを以下から入手してください。

64bit向けの最新Runnerはこちらからダウンロードしてください。
32bit向けの最新Runnerはこちらからダウンロードしてください。
任意のバージョンのRunnerはこちらとこちらをご参照いただき、直接URLを指定してダウンロードしてください。

入手した.exeファイルを先ほど作成したフォルダーにコピーします。

もしStep1でルートCAの証明書を用意した場合は、それを先ほど作成したフォルダーにコピーします。

続けて、先ほど作成したフォルダーへの書き込み権限と、Runnerの.exeファイルの実行権限を調整します。
例として、当方の検証環境ではUsersは読み取りのみに制限しました。

管理者権限でコマンドプロンプトを起動し、先ほど作成したGitLab Runnerのフォルダーへ移動します。

> cd ＜先ほど作成したGitLab Runnerのフォルダー＞

Runnerの登録コマンドを実行します。
なお、ここではRunnerの.exeファイルの名前がgitlab-runner-windows-amd64.exeである想定で記載していますが、それ以外の場合は適宜読み替えて実行してください。

> .\gitlab-runner-windows-amd64.exe register

前の手順でルートCAの証明書を用意した場合は以下のコマンドを実行してください。

> .\gitlab-runner-windows-amd64.exe register --tls-ca-file=＜用意したルートCAの証明書の絶対パス＞

他、registerコマンドのオプション一覧は以下のコマンドで確認可能です。

> .\gitlab-runner-windows-amd64.exe register --help

各種設定を対話式で指定していきます。
最初にGitLabのインスタンスURLを入力します。

Enter the GitLab instance URL (for example, https://gitlab.com/):
＜ご自身のGitLabのURLを入力します＞

GitLabインスタンスのURLがhttps://gitlab.example.comだった場合は以下のようになります。

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/

続いてRunnerのregistration tokenを入力します。
registration tokenの確認方法については、こちらのブログをご参照ください。
任意のスコープのRunnerのトークンを入力してください。

～略～
Enter the registration token:
＜ご自身のGitLabの任意のスコープのRunner registration tokenを入力します＞

このブログでは例としてShared runnerのトークンを使います。

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/
Enter the registration token:
qQVxxxxxxxxxxxxxxi5F

続いて、このRunnerの説明を任意で入力します。

～略～
[ホスト名]＜Runnerの説明を任意に入力します＞

このブログでは特に設定せずに次に進めます。

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/
Enter the registration token:
qQVxxxxxxxxxxxxxxi5F
Enter a description for the runner:
[ホスト名]

続いて、タグを任意で入力します。

～略～
Enter tags for the runner (comma-separated):
＜Runnerに付与したいタグを入力します＞

このブログでは、最後にCI/CDパイプラインでこのRunnerを明示的に使用してPowerShellコマンドの実行を試行するので、ws-runner-testというタグを付与します。

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/
Enter the registration token:
qQVxxxxxxxxxxxxxxi5F
Enter a description for the runner:
[ホスト名]
Enter tags for the runner (comma-separated):
ws-runner-test

続けて、メンテナンスノートを任意に入力します。

～略～
Enter optional maintenance note for the runner:
＜メンテナンスノートを任意に指定します＞

このブログでは特に設定せずに次に進めます。

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/
Enter the registration token:
qQVxxxxxxxxxxxxxxi5F
Enter a description for the runner:
[ホスト名]
Enter tags for the runner (comma-separated):
ws-runner-test
Enter optional maintenance note for the runner:

Runnerの登録結果がsucceededと表示されていることを確認します。

～略～
Registering runner... succeeded                  runner=<ランダムな文字列>

続けてエクゼキューターを入力します。
なお、選択可能なエクゼキューターの種類の順番は毎回変わります。以下の通りでなくても気になさらないでください。

～略～
Enter an executor: docker-ssh+machine, custom, docker-ssh, parallels, shell, ssh, virtualbox, docker, docker-windows, docker+machine, kubernetes:
＜使いたいエクゼキューターを指定します＞

このブログではshellを指定して次に進めます。

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/
Enter the registration token:
qQVxxxxxxxxxxxxxxi5F
Enter a description for the runner:
[ホスト名]
Enter tags for the runner (comma-separated):
ws-runner-test
Enter optional maintenance note for the runner:

Registering runner... succeeded                  runner=<ランダムな文字列>
Enter an executor: docker-ssh+machine, custom, docker-ssh, parallels, shell, ssh, virtualbox, docker, docker-windows, docker+machine, kubernetes:
shell

Runnerの登録が正常終了した旨のメッセージが表示されることを確認します。

～略～
Runner registered successfully. Feel free to start it, but if it's running already the config chould be automatically reloaded!

GUIからRunnerが登録されていることを確認します。
GitLabのGUIに管理者権限を有するユーザーでサインインし、[メニュー]>[管理者]を開きます。

[概要]>[Runner]でRunnerの一覧が表示されますので、先ほど登録したRunnerがあるか確認します。

Runnerの登録は以上となります。
後続手順でコマンドプロンプトを引き続き使用するので、開いたまま次の手順へ進んでください。

Step4 : Runnerのインストール (サービス登録)

RunnerをWindowsのサービスに登録します。
参考 : Install GitLab Runner on Windows | GitLab

Step3で使用していたコマンドプロンプトをそのまま用います。
以下のコマンドを実行します。

> .\gitlab-runner-windows-amd64.exe install

RunnerのサービスをLocal System以外の任意のユーザーで実行したい場合は、以下のようにオプションでユーザー名とパスワードを指定してください。

> .\gitlab-runner-windows-amd64.exe install --user ＜ユーザー名＞ --password ＜パスワード＞

Runnerのインストール (サービス登録) は以上となります。
後続手順でコマンドプロンプトを引き続き使用するので、開いたまま次の手順へ進んでください。

Step5 : Runnerの開始

Runnerのサービスを開始します。
参考 : Install GitLab Runner on Windows | GitLab

Step4で使用していたコマンドプロンプトをそのまま用います。
以下のコマンドを実行します。

> .\gitlab-runner-windows-amd64.exe start

Windowsのサービス一覧を開き、gitlab-runnerというサービスがあり、それが開始していることを確認します。

GUIからRunnerのステータスがオンラインになっていることを確認します。
GitLabのGUIに管理者権限を有するユーザーでサインインし、[メニュー]>[管理者]を開きます。

[概要]>[Runner]を開き、先ほど登録したRunnerのステータスが online になっていることを確認します。

Runnerの開始は以上となります。

Step6 : CI/CDパイプラインでPowerShellコマンドを試行

ここからは、今回登録したRunnerを明示的に使用してCI/CDパイプラインを実行します。
また、その際、任意のPowerShellコマンドを実行できるかを確認します。

まず、テスト用の空プロジェクトを1つ作成します。
この際、このプロジェクトが先ほど登録したRunnerを使用可能なName Spaceに作成してください。
空のプロジェクトの作成方法が不明な方は、こちらのブログをご参照いただきながら作成してください。

作成したプロジェクトの[設定]>[CI/CD]を開きます。

セクション[Runner]を展開し、このプロジェクトで使用可能なRunnerに今回登録したRunnerが表示されていることを確認します。
Runnerの丸いマークが緑色 (●) であれば使用可能です。
また、このブログではRunnerをShared runnerとして登録したため下図の赤枠部分に表示されていますが、Specific runnerもしくはGroup runnerとして登録した場合はそれぞれの場所に表示されています。

CI/CDパイプラインを作成するためにリポジトリにymlファイルを作成します。
[リポジトリ]>[ファイル]をクリックします。

[Web IDE]をクリックします。

新規ファイルのアイコンをクリックします。

[.gitlab-ci.yml]をクリックします。

.gitlab-ci.ymlにテスト用のパイプラインを記載します。
この時、以下を忘れずに設定なさってください。

表1. テスト用のymlファイルで設定すべきパラメーターと値
パラメーター	値
tages	今回登録したRunnerを明示的に使用するために、Runner登録時に指定したタグを指定してください。このブログの場合は`ws-runner-test`を指定します。
script	PowerShellコマンドを指定します。このブログの場合は`Get-Help Get-Random`を指定します。

当方で設定したymlファイルは以下の通りです。

stages:
    - RunnerTestStage

RunnerTestJob:
    stage: RunnerTestStage
    tags:
        - ws-runner-test
    script: 
        - echo "This is a test job for new runners."
        - echo "これは新しいRunnerのためのテストジョブです。"
        - sleep 10
        - Get-Help Get-Random

ymlファイルの入力が終わったら、[Create commit...]をクリックします。

[Commit to main branch]を選択し、[コミット]をクリックします。

コミット後、画面左下に表示されているCI/CDパイプラインの番号をクリックします。

パイプラインの詳細画面に遷移しますので、ジョブが完了するまで待機します。
完了したらジョブ名をクリックします。

画面右側にこのジョブを実行したRunnerが記載されていますので、これが今回登録したRunnerであることを確認します。
また、画面中央の出力結果にて、ymlファイルで指定したPowerShellコマンドが正常終了していることを確認します。
今回の場合はヘルプを表示するコマンドを試行しましたが、正常にコマンドが実行され、ヘルプの関する出力がされたことがわかります。

CI/CDパイプラインでPowerShellコマンドを試行する手順は以上となります。

【おまけ】エラーが出ちゃったときの対応

ここでは前述した作業中に、筆者が遭遇したエラーとその回避方法について簡単に記載致します。
もし同じエラーが出てしまった場合のご参考になれば幸いにございます。

名前解決できないよエラー

Runner登録時に出たエラーです。

ERROR: Registering runner... failed    runner=<RunnerID> status=couldn't execute POST against https://<GitLabインスタンスのURL>/api/v4/runners: Post "https://<GitLabインスタンスのURL>/api/v4/runners": dial tcp: lookup <GitLabインスタンスのホスト名>: no such host
PANIC: Failed to register the runner.

指定したGitLabインスタンスのURLをWindows OSから名前解決できなかったので出たエラーです。恥ずかしいミス。
GitLabのURLを名前解決できるように、DNSやhostsなど使って回避してください。

証明書が信頼できないよエラー

Runner登録時に出たエラーです。

ERROR: Registering runner... failed    runner=<RunnerID> status=couldn't execute POST against https://<GitLabインスタンスのURL>/api/v4/runners: Post "https://<GitLabインスタンスのURL>/api/v4/runners": x509: certificate signed by unknown authority
PANIC: Failed to register the runner.

当方の環境はローカルCAを使ってGitLabの証明書を発行しているため、このメッセージが出ました。
Step3でご紹介いたしました通り、ルートCAの証明書をWindows OSにコピーし、登録時のコマンドのオプション--tls-ca-fileでその証明書を指定することで回避できます。

pwsh へのパスがないよエラー

テスト用に作成したCI/CDパイプラインで出たエラーです。

ERROR: Job failed (system failure): prepare environment: failed to start process: exec: "pwsh": executable file not found in %PATH%. Check https://docs.gitlab.com/runner/shells/index.html#shell-profile-loading for more information

これは、当方が用意したWindows Server 2019にPowerShell Coreが入っていないにもかかわらず、Runnerのデフォルトシェルをpwshのまま使用したために出たエラーです。

回避方法として2通りあります。

一つは、Windows OS側にPowerShell Coreをインストールします。
PowerShell Coreをインストールすると、自動的にWindows OSにpwshへのパスが設定されるので、このエラーは出なくなります。
この回避方法を取る場合、RunnerのデフォルトシェルはPowerShell Coreのままです。

もう一つは、RunnerのデフォルトシェルをPowerShell Coreではなく、PowerShell Desktopに変更する方法です。
Runnerのデフォルトシェルは、Windows OSに作成したRunnerフォルダーの下に自動作成されているファイル config.toml を編集することで変更できます。
下図を参考に、config.toml ファイルの[[runners]] セクションにあるパラメーター shell をpwshからpowershellに変更します。

この変更により、このRunnerのデフォルトシェルはPowerShell Desktopとなり、上記のエラーは出なくなります。

CI/CDのご要件を考慮しつつ、いずれかの方法で回避してください。

そんなPowerShellコマンドないよエラー

テスト用に作成したCI/CDパイプラインで出たエラーです。

The term '<CI/CDパイプラインで指定したPowerShellコマンド>' is not recognized as a name of a cmdlet, function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

この時使用していた.gitlab-ci.ymlファイルはこちらでした。

stages:
    - RunnerTestStage

RunnerTestJob:
    stage: RunnerTestStage
    tags:
        - ws-runner-test
    script: 
        - echo "This is a test job for new runners."
        - echo "これは新しいRunnerのためのテストジョブです。"
        - sleep 10
        - Get-WmiObject Win32_ComputerSystemProduct

このRunnerはPowerShell Coreをデフォルトシェルに設定していたのですが、そもそもPowerShell CoreではコマンドGet-WmiObjectが存在しないために出たエラーです。
そりゃシェルで使えないコマンド実行しろっつったって無理な話デスヨネー。
CI/CDパイプラインでテスト的に実行するPowerShellコマンドを、Runnerのデフォルトシェルで実行可能なコマンドに変更してください。