企业官网建设流程全解析

如何把 Bitwarden CLI 配置为 Git credential helper 从保险库读取 HTTPS 凭据

【免费下载链接】clientsBitwarden client apps (web, browser extension, desktop, and cli).项目地址: https://gitcode.com/GitHub_Trending/cl/clients

当你在终端用git clone、git pull、git push操作 HTTPS 仓库时，Git 会弹出账号密码输入，或把明文凭据写进本地缓存。这篇文章解决的问题是：让 Git 在需要 HTTPS 凭据时，自动到 Bitwarden 保险库里去取。最终效果是——凭据保存在 Bitwarden 中，Git 每次操作时通过 Bitwarden CLI（bw）实时读取，不在本机留下额外的凭据文件。

仓库中已提供现成的 helper 脚本 git-credential-bw.sh，本文的所有步骤都围绕它展开。适用前提：

• 已安装 Git，目标仓库使用 HTTPS 地址（脚本只处理https协议）；
• 已安装 Bitwarden CLI 并能登录你的 Bitwarden 账号；
• 脚本使用 bash 关联数组（declare -A）和jq解析 JSON，运行环境需要 bash 与 jq。

准备条件：安装并登录 Bitwarden CLI

CLI 支持 Windows、macOS 和 Linux（见 apps/cli/README.md）。如果你已经在用 Node.js，文档推荐用 NPM 安装，方便后续更新：

npm install -g @bitwarden/cli

其他安装方式作为可选分支：

• 原生可执行文件：不需要 Node.js 运行时，可从 Bitwarden 官方文档的下载页获取；
• Chocolatey：choco install bitwarden-cli；
• Homebrew：brew install bitwarden-cli。注意 README 明确提醒：Homebrew 提供的是 GPL 构建，不包含企业 SSO 用户的 device approval 命令，不建议所有用户使用；
• Snap：sudo snap install bw。

安装完成后用--help验证 CLI 可用：

bw --help

CLI 对每条命令都自带--help说明，后续遇到不确定的命令可以直接这样查。

然后登录 Bitwarden（bw login）。登录状态会过期，脚本本身在运行时也会做检查，后面会讲。

在保险库中准备一条与主机名完全匹配的 Login 条目

脚本查找凭据的逻辑决定了保险库条目的格式要求，这一点必须先满足，否则后面一定失败：

1. 脚本会用bw list items --search "<host>"搜索条目，其中<host>是 Git 仓库地址里的主机名；
2. 搜索结果中，脚本用 jq 筛选条目 name 与 host 完全相等的那一条（select(.name == "<host>")）；
3. 再分别执行bw get username <id>和bw get password <id>取出账号和密码。

也就是说：你需要在 Bitwarden 里创建一条Login 类型条目，条目名称与仓库主机名一字不差（例如仓库是https://git.example.com/team/repo.git，条目名就写git.example.com），并且填好用户名和密码。

创建后先用 CLI 核对这条条目能被找到、凭据能取出来。<id>替换为你条目的 ID（bw list items --search返回的 JSON 里id字段，bw list --help可查看参数用法）：

bw list items --search "git.example.com" bw get username <id> bw get password <id>

如果bw list items --search能列出这条条目、bw get username/password能打印出非空值，说明保险库侧准备就绪。

放置 helper 脚本并注册 credential helper

把 git-credential-bw.sh 的内容保存为一个可执行文件，放到 PATH 中的某个目录（脚本注释里的说明是：放在 path 里，然后git config --global credential.helper bw）。Git 在credential.helper设为bw后，会按 credential helper 约定去 PATH 中查找并调用名为git-credential-bw的可执行程序——这就是仓库把脚本命名为git-credential-bw.sh的原因，你保存文件名时按此约定命名并赋予可执行权限即可。

脚本内容如下（保留了仓库中的逻辑与关键注释）：

#!/usr/bin/env bash # bw git-credential helper # A credential helper for git to retrieve usernames and passwords from bw. declare -A params if [[ "$1" == "get" ]]; then read -r line while [ -n "$line" ]; do key=${line%%=*} value=${line#*=} params[$key]=$value read -r line done if [[ "${params['protocol']}" != "https" ]]; then exit fi if [[ -z "${params["host"]}" ]]; then exit fi if ! bw list items --search "asdf" > /dev/null 2>&1; then echo "Please login to Bitwarden to use git credential helper" > /dev/stderr exit fi id=$(bw list items --search "${params["host"]}"|jq ".[] | select(.name == \"${params["host"]}\").id" -r) if [[ -z "$id" ]]; then echo "Couldn't find item id in Bitwarden DB." > /dev/stderr echo "${params}" exit fi user=$(bw get username "${id}") pass=$(bw get password "${id}") if [[ -z "$user" ]] || [[ -z "$pass" ]]; then echo "Couldn't find host in Bitwarden DB." > /dev/stderr exit fi echo username="$user" echo password="$pass" fi

脚本的行为边界，读代码即可确认：

• 只响应 Git 发来的get子命令，且只处理protocol=https；其他协议（如 ssh 仓库）直接静默退出，不干预；
• 用一条无意义的bw list items --search "asdf"探测登录态，失败时向 stderr 输出Please login to Bitwarden to use git credential helper；
• 全程只读保险库，不修改、不删除任何条目。

最后注册 helper（脚本注释中给出的命令）：

git config --global credential.helper bw

--global作用于本机所有仓库；如果只想对单个仓库生效，可以改用 git 常规的仓库级 scope 写法，脚本本身不需要任何改动。

验证配置是否生效

对一个需要账号密码的 HTTPS 仓库执行任意会触发认证的操作，例如：

git ls-remote https://git.example.com/team/repo.git

判断依据：

• 配置成功时，Git 不再提示输入密码，凭据由bw从保险库取出后交给 Git，操作正常完成；
• 如果保险库条目正确但仍失败，检查上面“准备条目”一节的两条命令是否都能输出预期值；
• 注意脚本对 ssh 协议和其他非 https 场景是静默退出的，不会有提示，这是设计行为而不是故障。

出错时按 stderr 信息定位

脚本有三条明确的错误输出，直接对应三类原因：

限制

• 只支持 HTTPS 协议的 Git 操作，脚本对非 https 直接退出；
• 条目匹配依赖“name 与 host 完全相等”，同名多个条目或名称不完全一致都会导致取不到 ID；
• 脚本依赖 bash 与 jq，bw命令需在运行 Git 的那个 shell 环境的 PATH 中可用；
• 每次 Git 认证都会实际调用bw查询保险库，前提是登录态有效。

以上步骤完成后，Git 对 HTTPS 仓库的认证请求就会持续从 Bitwarden 保险库解析凭据，仓库文件里只有这一条credential.helper配置。

【免费下载链接】clientsBitwarden client apps (web, browser extension, desktop, and cli).项目地址: https://gitcode.com/GitHub_Trending/cl/clients