Appearance
GitLab CI 集成
将签名安排在构建完成之后、发布之前。这里使用 Windows Shell Runner + PowerShell + VSign KSP + SignTool，签名或验证失败时停止任务。
配置签名 Runner
- 准备专用于可信发布任务的 Windows Runner，Shell 使用
powershell或pwsh，并设置标签windows-vsign。 - 使用实际运行 Runner 服务的 Windows 账户安装操作员、开启 KSP，完成 命令行签名 的单文件检查。
- 在该账户下确认能够访问时间戳服务，且签名不需要交互式输入。
不要用桌面管理员账户的测试结果代替 Runner 服务账户的测试结果。 Windows 的 LocalSystem 与您的登录账户使用不同的证书存储区。配置方法参考 Windows 服务签名说明。
将 Runner 设为受保护并限制到可信项目。拥有该执行账户的签名能力后，即使没有在 YAML 中放置密钥，不可信作业仍可能调用它；不要让未审查的合并请求或任意分支使用签名 Runner。
准备变量和脚本
在 GitLab 项目的 CI/CD 设置中配置以下变量，并限制为受保护引用可用：
| 变量 | 示例含义 |
|---|---|
SIGNTOOL_PATH | Runner 上 SignTool 的完整路径，含空格也可使用 |
SIGN_CERT_SHA1 | 预期发布证书的指纹 |
TIMESTAMP_URL | RFC 3161 时间戳服务地址 |
下载 sign-and-verify.ps1，经项目代码审查后保存到 ci/sign-and-verify.ps1。操作员在 Runner 主机上配置，不将安装 Token 放进 YAML、仓库或 artifacts。
加入签名作业
下面是加入现有流水线的签名作业。使用前请完成这些替换：
- 将
sign加入现有stages列表，置于构建之后、发布之前。 build_windows应替换为您的构建作业名；它必须在同一流水线运行，并上传release/your-app.exe作为 artifact。- 根据实际产物调整两个文件路径；这里仅处理一个 EXE。
- 发布标签须在 GitLab 中设置为受保护标签。签名作业和它依赖的构建作业都应在该标签流水线出现。
yaml
sign_windows:
stage: sign
tags:
- windows-vsign
needs:
- job: build_windows
artifacts: true
rules:
- if: '$CI_COMMIT_TAG && $CI_COMMIT_REF_PROTECTED == "true"'
- when: never
script:
- |
$ErrorActionPreference = 'Stop'
$source = Join-Path $env:CI_PROJECT_DIR 'release/your-app.exe'
$output = Join-Path $env:CI_PROJECT_DIR 'signed'
New-Item -ItemType Directory -Path $output -Force | Out-Null
$target = Join-Path $output 'your-app.exe'
Copy-Item -LiteralPath $source -Destination $target -Force
& "$env:CI_PROJECT_DIR/ci/sign-and-verify.ps1" -FilePath $target
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
artifacts:
when: on_success
paths:
- signed/your-app.exe
expire_in: 7 days发布作业只读取 sign_windows 成功后保存的 signed/your-app.exe，不要继续分发原始 release/your-app.exe。签名脚本发生失败时，不要设置 allow_failure: true 或忽略退出状态。
验证集成
使用测试项目和授权测试证书，先检查流水线语法，再运行一次完整的构建、签名和验签。下载 signed 制品，按 验证指南 核对发布者及时间戳。
另测试错误证书指纹、时间戳不可达和待签文件缺失三种情况，确认任务失败且不保存可发布制品。配置或证书更新后，重新验证这些条件。
| 问题 | 优先检查 |
|---|---|
| 作业一直等待 | Runner 是否在线、标签是否一致、引用是否受保护 |
needs 找不到构建任务 | 构建任务的名称及 rules 是否与标签流水线一致 |
| 证书不可见 | Runner 服务账户、当前用户证书存储区及 KSP |
| 作业卡住等待输入 | 操作员配置是否满足非交互签名，是否误用桌面会话 |
| 作业成功但下载到未签名文件 | artifact 路径及发布作业依赖 |