在 Windows 上安装极狐GitLab Runner | GitLab中文文档

1. Tier: 基础版, 专业版, 旗舰版

1. Offering: JihuLab.com, 私有化部署

要在 Windows 上安装和运行极狐GitLab Runner，您需要：

Git，可以从官方网站安装。
如果您希望在您的用户账户下运行它，而不是使用内置系统账户，则需要为您的用户账户设置密码。
系统区域设置为英语（美国）以避免字符编码问题。

安装#

在系统中创建一个文件夹，例如 C:\GitLab-Runner。
下载 64 位或 32 位的二进制文件，并将其放入您创建的文件夹中。以下假设您已将二进制文件重命名为 gitlab-runner.exe（可选）。您可以按照Bleeding Edge - 下载其他标记的版本中描述的方法下载每个可用版本的二进制文件。
确保限制极狐GitLab Runner 目录和可执行文件的 Write 权限。如果您不设置这些权限，普通用户可以用他们自己的可执行文件替换并以提升的权限运行任意代码。
运行一个提升的命令提示符：
注册一个 runner。
将极狐GitLab Runner 安装为服务并启动它。您可以使用内置系统账户（推荐）或用户账户运行该服务。

使用内置系统账户运行服务（在步骤 1 创建的示例目录下，C:\GitLab-Runner）
```
powershell
cd C:\GitLab-Runner
.\gitlab-runner.exe install
.\gitlab-runner.exe start
```
使用用户账户运行服务（在步骤 1 创建的示例目录下，C:\GitLab-Runner）

您必须为当前用户账户输入有效密码，因为 Windows 要求它来启动服务：
```
powershell
cd C:\GitLab-Runner
.\gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
.\gitlab-runner.exe start
```
如果您在极狐GitLab Runner 安装过程中遇到任何错误，请参阅故障排除部分。
（可选）在 C:\GitLab-Runner\config.toml 中更新 runner 的 concurrent 值，以允许多个并发作业，如高级配置详情中所述。此外，您还可以使用高级配置详情将您的 shell 执行器更新为使用 Bash 或 PowerShell，而不是 Batch。

完成！Runner 已安装、运行，并在每次系统重启后重新启动。日志存储在 Windows 事件日志中。

升级#

停止服务：

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

下载 64 位或 32 位的二进制文件并替换 runner 的可执行文件。您可以按照Bleeding Edge - 下载其他标记的版本中描述的方法下载每个可用版本的二进制文件。

启动服务：

powershell
.\gitlab-runner.exe start

卸载#

从一个提升的命令提示符运行：

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

Windows 故障排除#

确保您阅读了常见问题解答部分，该部分描述了一些极狐GitLab Runner 的常见问题。

如果您遇到类似 The account name is invalid 的错误，尝试：

powershell
# 在用户名之前添加 \.
.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"

如果您在启动服务时遇到 The service did not start due to a logon failure 错误，请参阅常见问题解答部分以了解如何解决此问题。

如果您没有 Windows 密码，您无法启动极狐GitLab Runner 服务，但可以使用内置系统账户。

有关内置系统账户问题，请参阅配置服务以使用内置系统账户启动在 Microsoft 支持网站上。

获取 runner 日志#

当您运行 .\gitlab-runner.exe install 时，它会将 gitlab-runner 安装为 Windows 服务。您可以在事件查看器中找到日志，提供者名称为 gitlab-runner。

如果您无法访问 GUI，可以在 PowerShell 中运行Get-WinEvent。

shell
1PS C:\> Get-WinEvent -ProviderName gitlab-runner
2
3   ProviderName: gitlab-runner
4
5TimeCreated                     Id LevelDisplayName Message
6-----------                     -- ---------------- -------
72/4/2021 6:20:14 AM              1 Information      [session_server].listen_address not defined, session endpoints disabled  builds=0...
82/4/2021 6:20:14 AM              1 Information      listen_address not defined, metrics & debug endpoints disabled  builds=0...
92/4/2021 6:20:14 AM              1 Information      Configuration loaded                                builds=0...
102/4/2021 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。
```
yaml
build:
  hooks:
    pre_get_sources_script:
      - $env:GIT_CONFIG_NOSYSTEM=''
```

构建自定义 GitLab-runner-helper 镜像：

dockerfile
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 中的批处理文件行前添加 call，使其看起来像 call C:\path\to\test.bat。以下是一个更完整的示例：

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

如何在 Web 终端上获得彩色输出？#

简短回答：

确保您的程序输出中有 ANSI 颜色代码。为了文本格式化，假设您正在运行 UNIX ANSI 终端仿真器（因为这是 Web 界面的输出）。

详细回答：

极狐GitLab CI 的 Web 界面模拟了一个 UNIX ANSI 终端（至少部分模拟）。gitlab-runner 将任何构建输出直接传递到 Web 界面。这意味着任何存在的 ANSI 颜色代码都会被识别。

旧版本的 Windows 命令提示符终端（在 Windows 10，版本 1511 之前）不支持 ANSI 颜色代码。它们使用 win32 调用，这些调用不会出现在要显示的字符串中。在编写跨平台程序时，开发人员通常默认使用 ANSI 颜色代码。当在 Windows 系统上运行时，这些代码被转换为 win32 调用，例如 Colorama。

如果您的程序执行了上述操作，则必须在 CI 构建中禁用该转换，以便 ANSI 代码保留在字符串中。

启动服务时出现 The service did not start due to a logon failure 错误#

在 Windows 上安装和启动极狐GitLab Runner 服务时，您可能会遇到此类错误：

shell
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 权限时，可能会发生此错误。在这种情况下，您需要为选定的用户添加此权限，然后重试启动服务。

转到 控制面板 > 系统和安全 > 管理工具。
打开 本地安全策略 工具。
在左侧列表中选择 安全设置 > 本地策略 > 用户权限分配。
在右侧列表中打开 作为服务登录。
选择 添加用户或组...。
手动添加用户（或使用 高级...）并应用设置。

根据 Microsoft 文档，此操作应适用于：

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

在某些 Windows 版本中，本地安全策略工具可能不可用，例如每个版本的“家庭版”变体。

在为服务配置中使用的用户添加 SeServiceLogonRight 后，命令 gitlab-runner start 应该能够顺利完成，且服务应能正确启动。

作业标记为成功或失败不正确#

大多数 Windows 程序输出 exit code 0 表示成功。然而，一些程序不会返回退出代码或使用不同的值表示成功。例如 Windows 工具 robocopy。以下 .gitlab-ci.yml 由于 robocopy 输出的退出代码而失败，即使它应该是成功的：

yaml
1test:
2  stage: test
3  script:
4    - New-Item -type Directory -Path ./source
5    - New-Item -type Directory -Path ./dest
6    - Write-Output "Hello World!" > ./source/file.txt
7    - robocopy ./source ./dest
8  tags:
9    - windows

在上述情况下，您需要手动向 script: 添加一个退出代码检查。例如，您可以创建一个 PowerShell 脚本：

powershell
1$exitCodes = 0,1
2
3robocopy ./source ./dest
4
5if ( $exitCodes.Contains($LastExitCode) ) {
6    exit 0
7} else {
8    exit 1
9}

并将 .gitlab-ci.yml 文件更改为：

yaml
1test:
2  stage: test
3  script:
4    - New-Item -type Directory -Path ./source
5    - New-Item -type Directory -Path ./dest
6    - Write-Output "Hello World!" > ./source/file.txt
7    - ./robocopyCommand.ps1
8  tags:
9    - windows

此外，当使用 PowerShell 函数时，请注意 return 和 exit 之间的区别。虽然 exit 1 会将作业标记为失败，但 return 1 不会。

使用 Kubernetes 执行器时作业被标记为成功并在中途终止#

有关更多信息，请参阅作业执行。

Docker 执行器：unsupported Windows Version#

极狐GitLab Runner 检查 Windows Server 的版本以验证其是否受支持。

它通过运行 docker info 来实现这一点。

如果极狐GitLab Runner 启动失败并显示错误但未指定 Windows Server 版本，则 Docker 版本可能已过时。

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

错误应包含有关 Windows Server 版本的详细信息，然后将其与极狐GitLab Runner 支持的版本进行比较。

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

Windows Server 上的 Docker 17.06.2 在 docker info 的输出中返回以下信息。

plaintext
Operating System: Windows Server Datacenter

在这种情况下，解决方法是升级 Docker 版本，使其与 Windows Server 发布的版本相当或更新。

Kubernetes 执行器：unsupported Windows Version#

Kubernetes 执行器在 Windows 上可能会遇到以下错误：

plaintext
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 节点选择器，例如：

toml
   [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 容器的服务：

使用为每个作业创建网络的网络模式。
确保启用了 FF_NETWORK_PER_BUILD 功能标志。

作业无法创建构建目录并失败并出现错误#

当您使用 GitLab-Runner 和 Docker-Windows 执行器时，作业可能会失败并出现类似错误：

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

当出现此错误时，请确保运行 Docker 引擎的用户对 C:\Program Data\Docker 具有完全权限。Docker 引擎必须能够为某些操作写入此目录，缺少正确权限则会导致失败。

阅读更多关于在 Windows 上配置 Docker 引擎的信息。

Windows Subsystem for Linux (WSL) 的 STDOUT 输出在作业日志中显示为空行#

默认情况下，Windows Subsystem for Linux (WSL) 的 STDOUT 输出未进行 UTF8 编码，并在作业日志中显示为空行。要显示 STDOUT 输出，您可以通过设置 WSL_UTF8 环境变量强制 WSL 进行 UTF8 编码。

yaml
job:
  variables:
    WSL_UTF8: "1"