GitHub Actions中Docker构建拉取私有仓库失败排查求助

问题描述 #

我有一个Poetry项目，依赖某GitHub私有仓库。本地运行、本地构建Docker镜像均正常，GitHub Actions的Lint任务也能正常拉取依赖，但在GHA中执行Docker构建时失败，报错HangupException: 远程服务器意外关闭连接。已知SSH密钥与AWS权限均正常，请分析问题原因并提供调试方法。

相关配置 #

Build YAML配置 #

build:
    needs: lint
    runs-on: ubuntu-latest

    permissions:
      id-token: write
      contents: read

    env:
      DOCKER_BUILD_FILE: "Dockerfile"
      DOCKER_BUILD_DIR: "."
      IMAGE_TAG: latest

    outputs:
      image_tag: ${{ steps.build-publish.outputs.image_tag }}
      full_image: ${{ steps.build-publish.outputs.full_image }}

    steps:
      - name: Set TARGET environment variables
        run: |
          TARGET_ENV="${{ github.ref_name }}"
          if [[ "$TARGET_ENV" == "main" ]]; then
            TARGET_ENV=test
          fi
          TARGET_ENV=$(echo "$TARGET_ENV" | tr '[:upper:]' '[:lower:]')
          echo "TARGET_ENV=$TARGET_ENV" >> $GITHUB_ENV

          TARGET_NAME="${{ github.event.repository.name }}-$TARGET_ENV"
          TARGET_NAME=$(echo "$TARGET_NAME" | tr '[:upper:]' '[:lower:]')
          echo "TARGET_NAME=$TARGET_NAME" >> $GITHUB_ENV

      - name: Check out the code
        uses: actions/checkout@v4

      - name: Set up SSH agent
        uses: webfactory/ssh-agent@v0.8.0
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
          debug-mode: true

      - name: Configure Git to use SSH
        run: |
          git config --global url."ssh://git@github.com/".insteadOf "https://github.com/"

      - name: Add GitHub to known hosts
        run: |
          mkdir -p ~/.ssh
          ssh-keyscan github.com >> ~/.ssh/known_hosts

      - name: Configure AWS Credentials
        id: aws-creds
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-region: ${{ vars.ACTIONS_AWS_REGION }}
          role-to-assume: arn:aws:iam::${{ vars.ACTIONS_AWS_ACCOUNT }}:role/${{ vars.ACTIONS_IAM_ROLE }}
          role-session-name: build-${{ env.TARGET_NAME }}

      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v2
        with:
          registries: ${{ vars.ACTIONS_AWS_ACCOUNT }}
          mask-password: "true"

      - name: Build, tag, and push image to Amazon ECR
        id: build-publish
        shell: bash
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: ${{ env.TARGET_NAME }}
          INCLUDE_DB: "false"
        run: |
          docker build --ssh default --build-arg="INCLUDE_DB=${INCLUDE_DB}" "${DOCKER_BUILD_DIR}" -f "${DOCKER_BUILD_FILE}" -t "$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG"
            docker push "$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG"

          echo "IMAGE $IMAGE_TAG is pushed to $ECR_REGISTRY/$ECR_REPOSITORY"

          echo "image_tag=$IMAGE_TAG" >> $GITHUB_OUTPUT
          echo "full_image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT

Poetry依赖配置 #

other_repo = { git = "ssh://git@github.com/my_company/other_repo.git" }

错误信息 #

HangupException
The remote server unexpectedly closed the connection.

原因分析 #

1. Docker构建上下文的SSH代理传递失效：GHA环境中配置的SSH代理未正确传递到Docker构建容器内，导致拉取私有仓库时认证失败，GitHub服务器主动关闭连接。
2. 构建容器内Git配置缺失：GHA宿主机的全局Git配置（如url.insteadOf规则）不会自动同步到容器，容器内拉取依赖时可能仍尝试用HTTPS而非SSH，触发认证失败。
3. SSH密钥权限异常：即使宿主机密钥权限正确，传递到容器后权限可能被修改（如过宽），导致SSH客户端拒绝使用该密钥，引发连接中断。
4. 网络波动或GitHub访问限制：GHA环境网络不稳定，或私有仓库的访问频率触发GitHub临时限制，导致连接意外关闭。

调试与解决方法 #

• 验证Docker构建时的SSH代理可用性：在Dockerfile中添加调试步骤，确认代理传递成功：

  RUN echo "检查SSH代理状态..." && ssh-add -l && ssh -T git@github.com
  

• 在Docker容器内配置Git与SSH：

  1. 强制Git使用SSH拉取GitHub仓库：

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

  2. 提前添加GitHub到容器的known_hosts：

     RUN mkdir -p ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
     

• 修正容器内SSH密钥权限：若手动复制密钥到容器，确保权限为600：

  RUN chmod 600 ~/.ssh/id_rsa
  

• 开启构建详细日志：

  1. 在GHA的docker build命令中添加--progress=plain参数，查看完整构建过程：

     docker build --ssh default --progress=plain --build-arg="INCLUDE_DB=${INCLUDE_DB}" "${DOCKER_BUILD_DIR}" -f "${DOCKER_BUILD_FILE}" -t "$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG"
     

  2. 开启Poetry详细日志，排查依赖拉取细节：

     ENV POETRY_VERBOSE=3
     

• 确认SSH密钥权限：检查该密钥对应的GitHub账号是否拥有目标私有仓库的读取权限，且密钥未过期、未被撤销。

• 增加Git克隆超时时间：在pyproject.toml中配置更长的克隆超时，避免网络波动导致中断：

  [tool.poetry.config.git]
  clone-timeout = 300
  

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