正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

WindowsにGitLab Runnerをインストールする

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

WindowsにGitLab Runnerをインストールして実行するには、以下が必要です:

  • Git（公式ウェブサイトからインストールできます）
  • ユーザーアカウントのパスワード（組み込みのシステムアカウントではなく、ユーザーアカウントで実行する場合）。
  • 文字エンコードの問題を回避するために、システムロケールが英語（米国）に設定されていること。詳細については、イシュー38702を参照してください。

インストール

  1. システム内の任意の場所（C:\GitLab-Runnerなど）にフォルダーを作成します。

  2. 64ビットまたは32ビットのバイナリをダウンロードし、作成したフォルダーに配置します。以降の説明では、バイナリの名前をgitlab-runner.exeに変更したこと（オプション）を前提としています。Bleeding Edge - その他のタグ付きリリースをダウンロードするの説明に従って、利用可能なすべてのバージョンのバイナリをダウンロードできます。

  3. GitLab Runnerのディレクトリと実行可能ファイルに対するWrite権限を制限してください。これらの権限を設定しないと、一般ユーザーが実行可能ファイルを独自のファイルに置き換え、管理者権限で任意のコードを実行してしまう可能性があります。

  4. 管理者権限でのコマンドプロンプトを実行します:

  5. Runnerを登録します。

  6. GitLab Runnerをサービスとしてインストールして開始します。組み込みのシステムアカウント（推奨）またはユーザーアカウントを使用してサービスを実行できます。

    組み込みのシステムアカウントを使用してサービスを実行する（ステップ1で作成したサンプルディレクトリC:\GitLab-Runner内）

    cd C:\GitLab-Runner
.\gitlab-runner.exe install
.\gitlab-runner.exe start

    ユーザーアカウントを使用してサービスを実行する（ステップ1で作成したサンプルディレクトリC:\GitLab-Runner内）

    現在のユーザーアカウントの有効なパスワードを入力する必要があります。これは、Windowsでサービスを開始するために必要であるためです:

    cd C:\GitLab-Runner
.\gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
.\gitlab-runner.exe start

    GitLab Runnerのインストール中にエラーが発生した場合は、トラブルシューティングのセクションを参照してください。

  7. （オプション）高度な設定の詳細で詳しく説明されているようにして、複数の同時ジョブを許可するため、C:\GitLab-Runner\config.tomlでRunnerのconcurrentの値を更新します。また、高度な設定の詳細を使用して、BatchではなくBashまたはPowerShellを使用するようにShell executorを更新できます。

これで、Runnerがインストールされ、実行され、システムを再起動するたびに再起動されるようになります。ログはWindowsイベントログに保存されます。

アップグレード

  1. サービスを停止します（以前と同様に管理者権限でのコマンドプロンプトが必要です）:

    cd C:\GitLab-Runner
.\gitlab-runner.exe stop

  2. 64ビットまたは32ビットのバイナリをダウンロードし、Runnerの実行可能ファイルを置き換えます。Bleeding Edge - その他のタグ付きリリースをダウンロードするの説明に従って、利用可能なすべてのバージョンのバイナリをダウンロードできます。

  3. サービスを開始します:

    .\gitlab-runner.exe start

アンインストール

管理者権限でのコマンドプロンプトから次のようにします:

cd C:\GitLab-Runner
.\gitlab-runner.exe stop
.\gitlab-runner.exe uninstall
cd ..
rmdir /s GitLab-Runner

Windowsのトラブルシューティング

FAQセクションを参照してください。このセクションでは、GitLab Runnerに関する最も一般的な問題について説明しています。

_アカウント名が無効です_のようなエラーが発生した場合は、以下を試してください:

# Add \. before the username
.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"

サービスの開始中にThe service did not start due to a logon failureエラーが発生した場合は、FAQセクションを参照して、問題を解決する方法を確認してください。

Windowsパスワードがない場合は、GitLab Runnerサービスを開始できませんが、組み込みのシステムアカウントを使用できます。

組み込みのシステムアカウントの問題については、MicrosoftのサポートウェブサイトのConfigure the Service to Start Up with the Built-in System Accountを参照してください。

Runnerのログを取得する

.\gitlab-runner.exe installを実行すると、gitlab-runnerがWindowsサービスとしてインストールされます。イベントビューアーで、プロバイダー名gitlab-runnerでログを見つけることができます。

GUIにアクセスできない場合は、PowerShellでGet-WinEventを実行できます。

PS C:\> Get-WinEvent -ProviderName gitlab-runner

   ProviderName: gitlab-runner

TimeCreated                     Id LevelDisplayName Message
-----------                     -- ---------------- -------
2/4/2025 6:20:14 AM              1 Information      [session_server].listen_address not defined, session endpoints disabled  builds=0...
2/4/2025 6:20:14 AM              1 Information      listen_address not defined, metrics & debug endpoints disabled  builds=0...
2/4/2025 6:20:14 AM              1 Information      Configuration loaded                                builds=0...
2/4/2025 6:20:14 AM              1 Information      Starting multi-runner from C:\config.toml...        builds=0...

Windowsでのビルド中にPathTooLongExceptionが発生する

このエラーは、npmなどのツールが、長さが260文字を超えるパスを含むディレクトリ構造を生成することがあるために発生します。この問題を解決するには、次のいずれかの解決策を採用します。

  • core.longpathsが有効になっているGitを使用します:

    Gitを使用してディレクトリ構造をクリーンアップすることで、問題を回避できます。

    1. コマンドラインからgit config --system core.longpaths trueを実行します。
    2. GitLab CIプロジェクト設定ページで、git fetchを使用するようにプロジェクトを設定します。

  • PowerShell用のNTFSSecurityツールを使用します:

    NTFSSecurity PowerShellモジュールには、長いパスをサポートするRemove-Item2メソッドが含まれています。このモジュールが利用可能な場合は、GitLab Runnerによってそれが検出され、自動的にそれが利用されます。

GitLab Runner 16.9.1で導入されたリグレッションは、GitLab Runner 17.10.0で修正されています。リグレッションのあるGitLab Runnerバージョンを使用する場合は、次のいずれかの回避策を使用してください:

  • pre_get_sources_scriptを使用することにより、Gitシステムレベルの設定を再度有効にします（Git_CONFIG_NOSYSTEMを設定解除します）。このアクションにより、Windowsでcore.longpathsがデフォルトで有効になります。

    build:
  hooks:
    pre_get_sources_script:
      - $env:GIT_CONFIG_NOSYSTEM=''

  • カスタムGitLab-runner-helperイメージをビルドします:

    FROM registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v17.8.3-servercore21H2
ENV GIT_CONFIG_NOSYSTEM=

Windows bashスクリプトを実行できません。The system cannot find the batch label specified - buildscriptと表示されます。

.gitlab-ci.ymlのBatchファイル行の先頭にcallを追加して、call C:\path\to\test.batのように記述する必要があります。サンプルの全体を次に示します:

before_script:
  - call C:\path\to\test.bat

詳細については、イシュー1025を参照してください。

Webターミナルで色付きの出力を得るにはどうすればよいですか？

簡単な説明:

プログラムの出力にANSIカラーコードが含まれていることを確認してください。テキストの書式設定という点から、UNIX ANSIターミナルエミュレーターで実行しているとします（これはウェブインターフェースの出力であるため）。

詳しい説明:

GitLab CIのウェブインターフェースは、UNIX ANSIターミナルをエミュレートします（少なくとも部分的に）。gitlab-runnerは、ビルドからの出力をウェブインターフェースに直接パイプします。つまり、存在するANSIカラーコードはすべて有効になります。

古いバージョンのWindowsのコマンドプロンプトターミナル（Windows 10、バージョン1511より前）は、ANSIカラーコードをサポートしていません。代わりにwin32（ANSI.SYS）呼び出しを使用しますが、この呼び出しは、表示される文字列に存在していません。クロスプラットフォームプログラムを作成する場合、デベロッパーは、通常、デフォルトでANSIカラーコードを使用します。このコードは、Windowsシステムで実行する場合（Coloramaなど）、win32呼び出しに変換されます。

ご使用のプログラムが上記の処理を実行している場合は、ANSIコードが文字列に残るように、CIビルドの変換を無効にする必要があります。

詳細については、GitLab CI YAMLドキュメントでPowerShellを使用する例を参照し、イシュー332を参照してください。

エラー: The service did not start due to a logon failure（コンポーネントビルドエラー: specは有効なJSONスキーマである必要があります）

WindowsにGitLab Runnerサービスをインストールして開始するときに、このエラーが発生する可能性があります:

gitlab-runner install --password WINDOWS_MACHINE_PASSWORD
gitlab-runner start
FATA[0000] Failed to start GitLab Runner: The service did not start due to a logon failure.

このエラーは、サービスの実行に使用されるユーザーがSeServiceLogonRight権限を持っていない場合に発生する可能性があります。この場合、選択したユーザーにこの権限を追加してから、サービスを再度開始する必要があります。

  1. Control Panel > System and Security > Administrative Toolsに移動します。
  2. Local Security Policyツールを開きます。
  3. 左側のリストでSecurity Settings > Local Policies > User Rights Assignmentを選択します。
  4. 右側のリストでLog on as a serviceを開きます。
  5. **Add User or Group…**を選択します。
  6. （手動で、または**Advanced…**を使用して）ユーザーを追加し、設定を適用します。

Microsoftドキュメントによると、これは次のWindowsバージョンで機能します:

  • Windows Vista
  • Windows Server 2008
  • Windows 7
  • Windows 8.1
  • Windows Server 2008 R2
  • Windows Server 2012 R2
  • Windows Server 2012
  • Windows 8

Local Security Policyツールは、一部のWindowsバージョン（各バージョンの「Home Edition」バリアントなど）では使用できない場合があります。

サービス設定で使用されているユーザーにSeServiceLogonRightを追加すると、コマンドgitlab-runner startが失敗せずに終了し、サービスが正常に開始されます。

ジョブが誤って成功または失敗としてマークされる

ほとんどのWindowsプログラムは、成功した場合にはexit code 0を出力します。ただし、一部のプログラムは終了コードを返さないか、成功時の値が異なることがあります。例として、Windowsツールrobocopyがあります。次の.gitlab-ci.ymlは成功するはずですが、robocopyによって出力された終了コードが原因で失敗します:

test:
  stage: test
  script:
    - New-Item -type Directory -Path ./source
    - New-Item -type Directory -Path ./dest
    - Write-Output "Hello World!" > ./source/file.txt
    - robocopy ./source ./dest
  tags:
    - windows

上記のケースでは、script:に終了コードチェックを手動で追加する必要があります。たとえば、PowerShellスクリプトを作成できます:

$exitCodes = 0,1

robocopy ./source ./dest

if ( $exitCodes.Contains($LastExitCode) ) {
    exit 0
} else {
    exit 1
}

.gitlab-ci.ymlファイルを次のように変更します:

test:
  stage: test
  script:
    - New-Item -type Directory -Path ./source
    - New-Item -type Directory -Path ./dest
    - Write-Output "Hello World!" > ./source/file.txt
    - ./robocopyCommand.ps1
  tags:
    - windows

また、PowerShell関数を使用する場合は、returnとexitの違いに注意してください。exit 1はジョブを失敗としてマークしますが、return 1はそのようにマークしません。

Kubernetes executorを使用しているときにジョブが成功としてマークされ、途中で終了した

詳細については、ジョブの実行を参照してください。

Docker executor: unsupported Windows Version

GitLab Runnerは、サポートされていることを確認するためにWindows Serverのバージョンを確認します。

このためにdocker infoを実行します。

GitLab Runnerが起動に失敗し、Windows Serverバージョンを指定せずにエラーを表示する場合、Dockerバージョンが古い可能性があります。

Preparation failed: detecting base image: unsupported Windows Version: Windows Server Datacenter

このエラーには、Windows Serverバージョンに関する詳細情報が含まれている必要があります。この情報が、GitLab Runnerがサポートするバージョンと比較されます。

unsupported Windows Version: Windows Server Datacenter Version (OS Build 18363.720)

Windows Server上のDocker 17.06.2は、docker infoの出力で以下を返します。

Operating System: Windows Server Datacenter

このケースでの修正策は、Windows Serverリリースと同程度の古いDockerバージョンを、それよりも新しいDockerバージョンをアップグレードすることです。

Kubernetes executor: unsupported Windows Version

Windows上のKubernetes executorは、次のエラーで失敗することがあります:

Using Kubernetes namespace: gitlab-runner
ERROR: Preparation failed: prepare helper image: detecting base image: unsupported Windows Version:
Will be retried in 3s ...
ERROR: Job failed (system failure): prepare helper image: detecting base image: unsupported Windows Version:

この問題を修正するには、GitLab Runner設定ファイルの[runners.kubernetes.node_selector]セクションにnode.kubernetes.io/windows-buildノードセレクターを追加します。次に例を示します:

   [runners.kubernetes.node_selector]
     "kubernetes.io/arch" = "amd64"
     "kubernetes.io/os" = "windows"
     "node.kubernetes.io/windows-build" = "10.0.17763"

マップされたネットワークドライブを使用しているが、ビルドが正しいパスを検出できない

管理者アカウントではなく標準ユーザーアカウントで実行されているGitLab Runnerは、マップされたネットワークドライブにアクセスできません。マップされたネットワークドライブを使用しようとすると、The system cannot find the path specified.エラーが発生します。このエラーは、サービスログオンセッションではリソースにアクセスする際にセキュリティ制限があるために発生します。代わりに、ドライブのUNCパスを使用します。

ビルドコンテナがサービスコンテナに接続できない

Windowsコンテナでサービスを使用するには、次のようにします:

ジョブがビルドディレクトリを作成できず、エラーで失敗する

Docker-Windows executorでGitLab-Runnerを使用すると、ジョブが次のようなエラーで失敗することがあります:

fatal: cannot chdir to c:/builds/gitlab/test: Permission denied`

このエラーが発生した場合は、Dockerエンジンの実行ユーザーに、C:\Program Data\Dockerに対する完全な権限があることを確認してください。Dockerエンジンは、特定のアクションでこのディレクトリに書き込むことができる必要がありますが、正しい権限がないと失敗します。

WindowsでのDocker Engineの設定の詳細を参照してください。

ジョブログのWindows Subsystem for Linux（WSL）STDOUT出力の空白行

デフォルトでは、Windows Subsystem for Linux（WSL）のSTDOUT出力はUTF8でエンコードされておらず、ジョブログに空白行として表示されます。STDOUT出力を表示するには、WSL_UTF8環境変数を設定して、WSLのエンコードを強制的にUTF8にすることができます。

job:
  variables:
    WSL_UTF8: "1"