我的 WSL / GitLab 凭据配置记录

本文记录我配置 WSL 与 GitLab 凭据时已确认的环境，并列出按 interop 状态选择方案的步骤。路径以文中安装布局为例，gitlab.xxx 表示需要替换的 GitLab 主机名。

通用原理、方案比较和完整排障说明见：《WSL 下 GitLab HTTP 用户名/密码凭据管理指南》。

1. 配置时已确认的环境

Windows Git                     正常
Windows Git Credential Manager  正常
GCM diagnose                    全部通过
credential.helper               manager
公司 GitLab                     自部署
协议                            HTTP
认证                            用户名 + 密码

当前仍需要根据 WSL interop 状态决定最终路线：

interop 可用：优先复用 Windows GCM；
interop 被彻底关闭：改用 Linux GCM + GPG/pass，或 credential cache。

2. 先确认 WSL interop

WSL 中执行：

cat /etc/wsl.conf
/mnt/c/Windows/System32/cmd.exe /c echo WSL-interop-ok

重点看：

1
[interop]
2
enabled=...
3
appendWindowsPath=...

判断：

显式路径能启动 cmd.exe：interop 可用；
command -v cmd.exe 没输出，但显式路径能运行：通常只是 appendWindowsPath=false；
显式路径也无法启动 Windows EXE：按完全隔离环境处理。

3. 路线 A：interop 可用时，复用 Windows GCM

3.1 Windows PowerShell：确认 GCM

git credential-manager --version
git credential-manager diagnose

3.2 查找当前机器上的 GCM EXE

我的 Git 安装根目录为：

E:\tool\git\Git

查找：

Get-ChildItem "E:\tool\git\Git" `
  -Filter "git-credential-manager.exe" `
  -Recurse `
  -ErrorAction SilentlyContinue |
  Select-Object -ExpandProperty FullName

预期位置类似：

E:\tool\git\Git\mingw64\bin\git-credential-manager.exe

3.3 Windows PowerShell：配置公司 GitLab

git config --global credential.gitlab.xxx.provider generic
git config --global credential.gitlab.xxx.allowWindowsAuth false

先不要机械开启：

git config --global credential.allowUnsafeRemotes true

只有当前 GCM/provider 明确因为 HTTP 拒绝发送凭据，并且已经明确接受 HTTP 风险时，再考虑开启。

3.4 WSL：验证并设置 helper

假设 GCM 实际路径确认为：

E:\tool\git\Git\mingw64\bin\git-credential-manager.exe

WSL 中测试：

"/mnt/e/tool/git/Git/mingw64/bin/git-credential-manager.exe" --version

配置：

git config --global credential.helper "/mnt/e/tool/git/Git/mingw64/bin/git-credential-manager.exe"

验证：

git config --show-origin --get-all credential.helper
git pull

首次认证成功后，预期链路：

WSL Git
  ↓
Windows GCM
  ↓
Windows Credential Manager
  ↓
公司 GitLab 用户名 / 密码

4. 路线 B：interop 被彻底关闭

如果：

1
[interop]
2
enabled=false

或者企业策略明确禁止 WSL 调用 Windows 程序，则不再尝试 Windows GCM。

4.1 需要长期安全保存：Linux GCM + GPG/pass

sudo apt update
sudo apt install gnupg pass

gpg --full-generate-key
gpg --list-secret-keys --keyid-format=long
pass init <YOUR_GPG_KEY_ID>

export GPG_TTY=$(tty)

安装 Linux GCM 后：

git-credential-manager configure
git config --global credential.credentialStore gpg
git config --global credential.gitlab.xxx.provider generic

4.2 不想配置 GPG：8 小时内存 cache

git config --global credential.helper 'cache --timeout=28800'

特点：不落盘，但 WSL 关闭、daemon 退出或超时后需要重新输入。

4.3 不使用 `credential.helper store` 作为默认方案

除非明确接受明文落盘，否则不要直接使用：

git config --global credential.helper store

chmod 600 ~/.git-credentials 只能限制文件读取权限，不会加密其中的密码。

5. 日常验证命令

5.1 WSL

git --version
command -v git
git remote -v
git config --show-origin --get-all credential.helper
git config --show-origin --get-regexp '^credential\.'
cat /etc/wsl.conf
/mnt/c/Windows/System32/cmd.exe /c echo WSL-interop-ok
"/mnt/e/tool/git/Git/mingw64/bin/git-credential-manager.exe" --version

5.2 Windows PowerShell

git --version
where.exe git
git credential-manager --version
git credential-manager diagnose
git config --show-origin --get-all credential.helper
git config --show-origin --get-regexp '^credential\.'

6. 出问题时的恢复步骤

6.1 清除当前 GitLab 的错误凭据

printf 'protocol=http\nhost=gitlab.xxx\n\n' | git credential reject

然后重新：

git pull

6.2 清空 credential cache

git credential-cache exit

6.3 helper 配错时回退

git config --show-origin --get-all credential.helper
git config --global --unset-all credential.helper
git config --show-origin --get-regexp '^credential\.'

先用 --show-origin 确认配置来源，不直接删除来源不明的系统级配置。

7. 安全提醒

当前环境最大的安全限制仍然是 GitLab 只提供 HTTP。

本地使用 Windows Credential Manager、GPG/pass 或内存 cache，只能改善“密码在本机如何保存”，不能给 HTTP 链路增加 TLS 提供的机密性和服务器身份验证。

长期方向仍然是推动提供 HTTPS、SSH、deploy token / deploy key、PAT 或其他受控的机器凭据。