From 0e728e1f7b76cd48d735b11d8e643372e7f37e85 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BE=90=E5=8B=A4=E6=B0=91?= <xuqinmin@bjca.org.cn>
Date: Mon, 27 Jul 2026 12:53:24 +0800
Subject: [PATCH] ci: support Windows SSH credential binding

---
 Jenkinsfile                    | 6 +++++-
 docs/IMPLEMENTATION_HANDOFF.md | 3 +++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/Jenkinsfile b/Jenkinsfile
index 6538d21..15b90cc 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -110,10 +110,14 @@ print('versions.json updated: symbolicator = ${env.IMAGE_VERSION}')
 
     stage('Commit Version') {
       steps {
-        sshagent(credentials: ['jenkins-ssh-key']) {
+        withCredentials([sshUserPrivateKey(
+          credentialsId: 'jenkins-ssh-key',
+          keyFileVariable: 'GIT_SSH_KEY'
+        )]) {
           script {
             bat """
               chcp 65001 >nul
+              set "GIT_SSH_COMMAND=ssh -i %GIT_SSH_KEY% -o IdentitiesOnly=yes"
               git config user.email "jenkins@xuqm.com"
               git config user.name "Jenkins CI"
               git add ${env.VERSION_FILE}
diff --git a/docs/IMPLEMENTATION_HANDOFF.md b/docs/IMPLEMENTATION_HANDOFF.md
index 14343a9..a8d7d8e 100644
--- a/docs/IMPLEMENTATION_HANDOFF.md
+++ b/docs/IMPLEMENTATION_HANDOFF.md
@@ -45,5 +45,8 @@ docker build -t xuqm-symbolicator:local .
 
 - 不得恢复 `npm install` 容器构建或忽略锁文件。
 - 不得把 Jenkins 仓库地址改回包含 Token 的 URL；现有 SSH credentials 方案是基线。
+- Windows Jenkins 的 OpenSSH Agent 以系统服务运行，`ssh-agent` Pipeline 插件无法解析
+  其空输出；Git 推送必须通过 `sshUserPrivateKey` 临时文件和当前进程
+  `GIT_SSH_COMMAND` 使用密钥，禁止退回凭据化 URL。
 - 不得在日志中输出认证信息或完整异常输入。
 - 不得在没有显式限额与清理策略时启用 multipart 上传。