Github Actions中使用Deploy Key安装Poetry依赖失败排查

1. SSH代理环境未被Poetry继承：webfactory/ssh-agent配置的SSH代理环境变量（如SSH_AUTH_SOCK）可能没有在Poetry执行的步骤中正确传递，导致Poetry调用Git时无法找到可用的SSH密钥。
2. Deploy Key格式不兼容：部分新版本OpenSSH生成的密钥格式（如ssh-ed25519开头的非PEM格式）可能无法被Poetry调用的Git进程识别，引发密钥无效的错误。
3. Git默认协议冲突：Poetry在处理Git依赖时，可能内部默认使用HTTPS协议拉取，而非配置的SSH地址，导致Deploy Key无法生效，出现权限拒绝。
4. 密钥配置细节问题：Deploy Key可能存在多余换行、空格，或者未正确添加到目标私有仓库的Deploy Keys列表中（虽然git clone成功，但不排除Poetry执行时的环境差异）。

• 确保SSH代理环境变量传递：在Github Actions的工作流中，执行poetry install前，确认SSH_AUTH_SOCK环境变量已被正确继承。可以通过echo $SSH_AUTH_SOCK验证，或者使用webfactory/ssh-agent提供的setup-ssh步骤自动注入环境变量。
• 转换Deploy Key为PEM格式：如果使用的是新格式SSH密钥，执行以下命令转换为PEM格式：

  ssh-keygen -p -f your_deploy_key_file -m pem
  

  然后在Github Actions的密钥管理中更新为转换后的密钥内容。
• 强制Git使用SSH协议：在执行poetry install前添加Git全局配置，将Github的HTTPS地址自动替换为SSH：

  git config --global url."git@github.com:".insteadOf "https://github.com/"
  

  这样即使Poetry内部尝试用HTTPS拉取，也会自动转为SSH协议，复用已配置的Deploy Key。
• 验证Deploy Key权限与配置：再次确认目标私有仓库的Deploy Keys列表中已添加该密钥，且权限为只读；同时检查密钥内容无多余字符，确保粘贴到Github Actions Secrets时没有格式错误。
• 显式指定Poetry的Git环境：在Github Actions步骤中，执行poetry install前先激活SSH代理，例如：

  eval $(ssh-agent -s)
  ssh-add - <<< "$DEPLOY_KEY"
  

  （替代webfactory/ssh-agent的方式，直接手动加载密钥，避免代理环境传递问题）

Poetry本身不直接管理或处理Deploy Key，它依赖系统环境中的Git命令来拉取私有仓库依赖。只要系统环境已正确配置SSH代理并加载了Deploy Key，Poetry就能正常通过SSH访问私有仓库，因此Poetry完全支持通过Deploy Key访问私有Git依赖，问题通常出在环境配置的传递或兼容性上。

内容的提问来源于stack exchange，提问作者shelper