- 安装
- 升级
- 卸载
- Windows 版本支持政策
-
Windows 故障排除
- 获取 Runner 日志
- 在 Windows 上进行构建时出现 PathTooLongException
- 无法运行 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
- 使用映射网络驱动,构建无法找到正确路径
- 构建容器无法连接服务容器
- 作业无法创建构建目录,出现错误并失败
在 Windows 上安装极狐GitLab Runner
在 Windows 上安装和运行极狐GitLab Runner,您需要:
- Git,您可以从官方网站安装。
- 您的用户帐户的密码,如果您想在您的用户账号而不是内置系统帐户下运行它。
安装
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 版本支持政策
我们遵循和微软服务渠道版一样的生命周期策略。
也就是说,我们支持:
我们发行的 Windows 二进制 和 Docker 执行器都是一样的情况。
在 Windows 版本不再获得微软的主流支持后,
我们正式弃用版本并且在下一次重大更改中将其移除。例如,在 12.x 中,我们开始支持 Windows 1803
,
因为它出现在 2018-04-30
上。主流支持于 2019-11-12
结束,所以我们在 12.x 中弃用了 Windows 1803
。
作为单一的事实来源,我们使用 https://learn.microsoft.com/en-us/lifecycle/products/ 指定 发布日期和主流支持日期。
以下是常用版本及其支持终止的日期列表:
OS | 主流支持结束日期 |
---|---|
Windows 10 1809/2019 | 2024.01 |
Windows Server Datacenter 1809/2019 | 2024.01 |
Windows Server Datacenter 1903 | 2020.12 |
未来发布
微软每年在半年度渠道版中发布 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 发布更高的版本。
使用映射网络驱动,构建无法找到正确路径
如果极狐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 引擎必须能够写入此目录以执行某些操作,如果没有正确的权限,它会失败。