使用cibuildwheel认证私有GitHub仓库部署密钥的问题

我使用cibuildwheel为Python项目构建和测试Wheel包，该工具通过Docker镜像实现跨平台构建。所有GitHub Runner上的构建流程均正常，但Ubuntu和Windows平台的测试环节失败，原因是安装私有GitHub仓库依赖时出现SSH认证错误。

错误日志 #

ubuntu-latest 错误 #

Running command git clone --filter=blob:none --quiet 'ssh://****@github.com/org/repo.git' /tmp/pip-install-6xye89_k/repo_hash
error: cannot run ssh: No such file or directory
fatal: unable to fork

windows-latest 错误 #

Running command git clone --filter=blob:none --quiet 'ssh://****@github.com/org/repo.git' 'C:\Users\runneradmin\AppData\Local\Temp\pip-install-ejq4b3y5\repo_hash'
Host key verification failed.
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.

原配置 #

pyproject.toml 中的 cibuildwheel 配置 #

[tool.cibuildwheel]
build-verbosity = 1
build           = "cp310-* cp311-*"
test-command    = "python -c 'import my_pkg; import my_pkg.my_module'"

[tool.cibuildwheel.linux]
archs = "x86_64"

[tool.cibuildwheel.macos]
before-test = "brew install hdf5 && export HDF5_DIR=\"$(brew --prefix hdf5)\""

GitHub Workflow 作业配置 #

build-wheels:
  runs-on: ${{ matrix.os }}
  strategy:
    fail-fast: false
    matrix:
      os: [ubuntu-latest, macos-13, macos-14, windows-latest]

  steps:
    - uses: actions/checkout@v4

    - name: authenticate with private repo deployed key
      uses: webfactory/ssh-agent@v0.8.0
      with:
        ssh-private-key: |
          ${{ secrets.REPO_DEPLOY_KEY }}

    - name: build wheels
      uses: pypa/cibuildwheel@v2.20.0

    - name: upload wheels
      uses: actions/upload-artifact@v4.3.6
      with:
        name: wheels-${{ matrix.os }}
        path: wheelhouse/*

尝试过的无效方法 #

• 为Linux安装openssh-clients：解决了ssh命令缺失问题，但仍出现主机密钥验证失败错误
• 直接传递SSH_AUTH_SOCK环境变量：未生效

最终解决方案 #

Linux平台修复 #

修改pyproject.toml中的Linux配置，正确传递SSH代理套接字并添加GitHub主机密钥：

[tool.cibuildwheel.linux]
environment = { SSH_AUTH_SOCK = "/host$SSH_AUTH_SOCK" }
environment-pass = ["SSH_AUTH_SOCK"]
before-test = """
    yum install -y openssh-clients && \
    mkdir -p ~/.ssh && \
    chmod 700 ~/.ssh && \
    ssh-keyscan github.com >> ~/.ssh/known_hosts
"""

配置说明：

• environment和environment-pass：将主机的SSH_AUTH_SOCK路径转换为容器内可访问的路径并传递，让容器能使用外部的ssh-agent服务
• before-test：安装openssh客户端，创建并配置.ssh目录权限，扫描GitHub主机密钥添加到已知主机列表，避免密钥验证失败

Windows平台修复 #

无需修改pyproject.toml，原Workflow配置即可正常工作。

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