github actions 中私钥管理核心原则是绝不硬编码、全部通过 secrets 管理并按需加载：私钥须存入仓库 secrets（命名合规、含完整 pem 块），工作流中用 webfactory/ssh-agent 等成熟 action 安全注入；api token、docker 凭据等按用途分别注入 env 或 action with 参数；严禁 run 中输出密钥、避免结构化数据作 secret 值，且私钥生成不可设 passphrase。
GitHub Actions 中使用私有密钥的核心原则是：**绝不硬编码，全部走 Secrets 管理，并按需加载到运行环境中**。关键不在于“怎么写”，而在于“怎么安全地传、怎么正确地用”。
把私钥存进 GitHub Secrets
这是第一步，也是最基础的安全防线：
- 进入仓库 → Settings → Security → Secrets and variables → Actions
- 点击 New repository secret
- Name 填一个清晰名称（如 SSH_PRIVATE_KEY 或 DEPLOY_KEY），注意不能以数字开头、不能含空格或特殊符号
- Secret 字段粘贴私钥的完整内容（包括
-----BEGIN OPENSSH PRIVATE KEY-----到-----END OPENSSH PRIVATE KEY-----） - 保存后，该密钥就只对工作流可见，且日志中自动屏蔽为
***
在工作流里加载并使用 SSH 私钥
常见场景是克隆私有仓库或部署到远程服务器，推荐用社区成熟 Action：
- 使用 webfactory/ssh-agent@v0.9.0（轻量、专注 SSH）
- 在 steps 中添加：
- uses: webfactory/ssh-agent@v0.9.0 with: ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} - 后续所有
git clone git@github.com:org/private-repo.git或ssh user@host都会自动复用该密钥 - 无需手动启动 agent、设置环境变量或写入磁盘，密钥全程驻留内存
其他类型私钥的用法差异
不是所有私钥都走 SSH 流程，要区分用途：
-
API Token / CLI 密钥（如 Vercel、EdgeOne、微信云托管）：直接作为环境变量注入，例如：
env: VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }} -
Docker Registry 登录凭据：用
docker/login-action，传username和password（分别对应两个 Secrets） - JWT 签名密钥或加密密钥：建议单独建 Secret，避免和结构化数据混用（比如不要把 JSON 对象整个当 Secret 值）
必须避开的安全陷阱
很多问题其实出在配置细节上：
- 私钥生成时不要设密码（passphrase），否则
ssh-agent无法无交互加载 - 公钥必须正确添加到目标服务（如 GitHub Deploy Keys、服务器
~/.ssh/authorized_keys） - 工作流中若用
run执行命令输出了密钥（哪怕只是 echo $VAR），会导致泄露——GitHub 不会自动掩码未声明为 Secret 的变量 - 组织级或环境级 Secret 优先级高于仓库级，同名时低层级覆盖高层级，命名要统一规划
