在 Windows 上安装极狐GitLab Runner (BASIC ALL)

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

Git，您可以从官方网站安装。
您的用户账户的密码，如果您想在您的用户账号而不是内置系统账户下运行它。

安装

在极狐GitLab Runner 10 中，可执行文件重命名为 gitlab-runner。

在您的系统中创建文件夹，如：C:\GitLab-Runner。
下载 64-位或 32-位的二进制文件并把它放在您创建的文件夹里。假设您将二进制文件重命名为 gitlab-runner.exe（可选）。您可以为每个前沿 - 下载其他标签发布中的可用版本下载二进制文件。
确保在极狐GitLab Runner 目录和可执行文件中限制 Write 权限。如果您没有设置这些权限，普通用户将可以随意替换二进制文件并使用升级的权限随意运行代码。
运行升级的命令提示：
注册 Runner.
将极狐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 的过程中遇到任何问题，请参见故障排除部分。
（可选）在 C:\GitLab-Runner\config.toml 中更新 Runner 的 concurrent 值, 允许多个如高级配置详细信息中所描述的并发作业。此外，您可以使用高级配置详细信息更新您的 Shell 执行器，以使用 Bash 或 PowerShell 而不是 Batch。

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

升级

停止服务（跟之前一样，您需要升级的命令提示）：
```
cd C:\GitLab-Runner
.\gitlab-runner.exe stop
```
下载 64-位或 32-位的二进制文件并替换 Runner 的可执行文件。您可以为每个前沿 - 下载其他标签发布中的可用版本下载二进制文件。
启动服务：
```
.\gitlab-runner.exe start
```

卸载

从升级的命令提示：

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

Windows 版本支持政策

极狐GitLab 正式支持 Microsoft Windows 操作系统的 LTS 版本，因此我们遵循 Microsoft 服务渠道生命周期政策。

也就是说，我们支持：

发布日期后 5 年内的长期服务渠道版版本。请注意，我们不支持扩展支持的版本。
发布日期后 18 个月内的半年度渠道版版本。主流支持结束后，我们将不再支持这些版本。

我们发行的 Windows 二进制和 Docker 执行器都是一样的情况。

Windows 容器的 Docker 执行器有严格的版本要求，因为容器必须匹配主机操作系统的版本。更多内容请参见支持的 Windows 容器列表。

极狐GitLab 提供 Windows 操作系统 Runner 镜像，直至操作系统的 EOL（生命周期结束）日期。Windows 操作系统 EOL 日期之后，极狐GitLab 将停止发布 EOL Windows 操作系统版本的 Runner 镜像。

Windows 操作系统版本的 EOL 日期不一定与极狐GitLab 主要版本一致；因此，我们通常不会在极狐GitLab 次要版本中发布 EOL 镜像。

作为单一的事实来源，我们使用 https://learn.microsoft.com/en-us/lifecycle/products/ 指定发布日期和主流支持日期。

以下是常用版本及其支持终止的日期列表：

OS	主流支持结束日期
Windows 10 1809/2019	2024.01
Windows Server Datacenter 1809/2019	2024.01

未来发布

微软每年在半年度渠道版中发布 2 次新的 Windows Server 产品，并且每 2 - 3 年在长期服务渠道 (LTSC) 中更新一次新的 Windows Sever 的主要版本。

极狐GitLab 旨在测试和发布新的极狐GitLab Runner Helper 镜像，它在 Google Cloud Platform 上正式发布微软版本的 1 个月内包含最新的 Windows Server 版本（半年渠道版）。可用日期请参见服务选项列表的 Windows 服务器当前版本。

Windows 故障排除

请阅读 FAQ，它介绍了您在使用极狐GitLab Runner 时最可能遇到的问题。

如果您遇到类似账户名不可用之类的错误，请尝试在用户名前添加 .\：

.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"

如果您在启动服务时遇到登录失败，服务未启动的错误，请访问 FAQ以查看如何解决问题。

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

如果您对内置系统账户有疑问，请在 Microsoft 的支持网站上阅读使用内置系统账户配置服务进行启动。

获取 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/2021 6:20:14 AM              1 Information      [session_server].listen_address not defined, session endpoints disabled  builds=0...
2/4/2021 6:20:14 AM              1 Information      listen_address not defined, metrics & debug endpoints disabled  builds=0...
2/4/2021 6:20:14 AM              1 Information      Configuration loaded                                builds=0...
2/4/2021 6:20:14 AM              1 Information      Starting multi-runner from C:\config.toml...        builds=0...

在 Windows 上进行构建时出现 PathTooLongException

This is caused by tools like npm which will sometimes generate directory structures with paths more than 260 characters in length. There are two possible fixes you can adopt to solve the problem. 这是由诸如 npm 之类的工具引起的，这些工具有时会生成路径长度超过 260 个字符的目录结构。您可以采用两种可能的修复方法解决这个问题。

a) 使用 Git 并启用 core.longpaths

您可以通过使用 Git 清理目录结构来避免该问题，首先运行 git config --system core.longpaths true 命令，然后设置您的项目，使用极狐GitLab CI 项目设置页面中的 git fetch。

b) 使用 PowerShell 的 NTFSSecurity 工具

NTFSSecurity PowerShell 模块提供支持长路径的 Remove-Item2 方法。极狐GitLab Runner 将检测它是否可用并自动使用它。

无法运行 Windows BASH 脚本，出现 `The system cannot find the batch label specified - buildscript`

您需要在 .gitlab-ci.yml 中将 call 添加到批处理文件行，使其看起来像 call C:\path\to\test.bat。如下例所示：

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

如何在网页终端上获得彩色输出？

短答案：

确保程序输出中有 ANSI 颜色代码。出于文本格式的目的，假设您在 UNIX ANSI 终端仿真器中进行运行（因为这就是 webUI 输出）。

长答案：

极狐GitLab CI 的 Web 界面模拟 UNIX ANSI 终端（至少部分模拟）。gitlab-runner 将构建的输出直接传送到网页界面。

老版本的 Windows CMD 终端（Win10 1511 版之前）不支持 ANSI 颜色代码 - 他们使用 win32 (ANSI.SYS) 调用而不是显示字符串中不存在的调用。在编写跨平台程序时，开发人员通常会默认使用 ANSI 颜色代码并将其转换为运行在 Windows 系统上的 win32 调用（例如：Colorama）。

如果您的程序正在进行上述操作，您需要为 CI 构建禁用转换，这样 ANSI 代码可以一直保留在字符串中。

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

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

访问 Control Panel > System and Security > Administrative Tools。
打开 Local Security Policy 工具。
在左侧列表中选择 Security Settings > Local Policies > User Rights Assignment。
在右侧列表中打开 Log on as a service。
单击 Add User or Group… 按钮。
添加用户（”手动” 或使用 Advanced… 按钮）并应用设置。

根据微软文档，它适用于：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 版本中不可用 - 例如每个版本的 “家庭版” 变体。

为服务配置中使用的用户添加 SeServiceLogonRight 后，命令 gitlab-runner start 应该会成功完成并且服务应该正确启动。

作业被错误地标记成功或失败

Most Windows programs output exit code 0 for success. However, some programs don’t return an exit code or have a different value for success. An example is the Windows tool robocopy. The following .gitlab-ci.yml fails, even though it should be successful, due to the exit code output by robocopy: 大多数 Windows 程序输出 exit code 0 表示成功。但是，有些程序没有返回退出代码或输出其他值表示成功。一个例子是 Windows 工具 robocopy。由于 robocopy 输出退出代码，即使不应该，但是以下 .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
    - 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 执行器将作业标记为成功和中途停止

请参见作业执行。

Docker 执行器：`unsupported Windows Version`

极狐GitLab Runner 运行 docker info 检查 Windows Server 的版本，验证它是否受支持。

如果极狐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

这种情况的解决方法是升级同样版本的 Docker 版本，或者比 Windows Server 发布更高的版本。

Kubernetes 执行器：`unsupported Windows Version`

Windows 上的 Kubernetes 执行器可能会失败并出现以下错误：

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 nodeSelector，例如：

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

使用映射网络驱动，构建无法找到正确路径

如果极狐GitLab Runner 不是在管理员账户，而是在标准用户账户下运行，则无法使用映射的网络驱动，并且您将收到一条错误消息： 系统找不到指定的路径。这是因为使用服务登录会话会在访问安全资源时产生限制。您应该使用您驱动的 UNC 路径。

构建容器无法连接服务容器

通过 Windows 容器使用服务：

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

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

当您通过 Docker-Windows 执行器使用 GitLab-Runner 时，作业或许会失败并出现以下错误：

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

发生此错误时，请确保运行 Docker 引擎的用户对 C:\Program Data\Docker 具有完全权限。 Docker 引擎必须能够写入此目录以执行某些操作，如果没有正确的权限，它会失败。

阅读更多在 Windows 上配置 Docker Engine 的内容。

在 Windows 上安装极狐GitLab Runner (BASIC ALL)

安装

升级

卸载

Windows 版本支持政策

未来发布

Windows 故障排除

获取 Runner 日志

在 Windows 上进行构建时出现 PathTooLongException

a) 使用 Git 并启用 core.longpaths

b) 使用 PowerShell 的 NTFSSecurity 工具

无法运行 Windows BASH 脚本，出现 The system cannot find the batch label specified - buildscript

如何在网页终端上获得彩色输出？

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

作业被错误地标记成功或失败

使用 Kubernetes 执行器将作业标记为成功和中途停止

Docker 执行器：unsupported Windows Version

Kubernetes 执行器：unsupported Windows Version

使用映射网络驱动，构建无法找到正确路径

构建容器无法连接服务容器

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

无法运行 Windows BASH 脚本，出现 `The system cannot find the batch label specified - buildscript`

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

Docker 执行器：`unsupported Windows Version`

Kubernetes 执行器：`unsupported Windows Version`