GitHub Actions使用GHCR镜像时Docker登录间歇性失败问题排查

问题场景 #

使用自托管GitHub Actions Runner运行以下工作流，指定GHCR私有镜像作为容器环境：

name: My Workflow
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: [selfhosted]
    container:
      image: ghcr.io/myorg/myrepo/node:18
    steps:
      - name: Echo
        run: echo "Hello"

在Initialize container步骤中，GitHub Actions自动使用GITHUB_TOKEN登录GHCR时出现间歇性失败，无固定复现规律，错误提示：

Docker login for 'ghcr.io' failed with exit code 1

查看自托管Runner上的Docker守护进程日志，发现核心错误：

level=info msg="Error logging in to endpoint, trying next endpoint" error="Get https://ghcr.io/v2/: remote error: tls: internal error"
level=error msg="Handler for POST /v1.41/auth returned error: Get https://ghcr.io/v2/: remote error: tls: internal error"

错误含义解析 #

• remote error: tls: internal error是TLS握手阶段的底层系统级错误，并非GHCR服务返回的业务错误，本质是本地Docker客户端与GHCR服务器的TLS连接过程中出现了兼容性、资源或网络层面的间歇性故障。
• 间歇性出现说明配置本身无问题（否则会稳定失败），大概率是自托管Runner主机的TLS库兼容bug、网络波动、Docker资源不足或证书缓存异常导致。

解决办法 #

1. 升级主机TLS依赖库 #

老旧版本的OpenSSL/GnuTLS可能存在与GHCR TLS 1.3协议协商的间歇性兼容问题，直接升级相关依赖：

• Debian/Ubuntu系统：

  apt update && apt upgrade -y openssl libssl-dev
  

• RHEL/CentOS系统：

  yum update -y openssl openssl-devel
  

2. 强制指定Docker TLS协议版本 #

修改Docker守护进程配置文件（通常为/etc/docker/daemon.json），限制TLS协议版本，避免自动协商时的异常：

{
  "tls-min-version": "TLSv1.2",
  "tls-cipher-suites": "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384"
}

重启Docker生效：

systemctl restart docker

3. 清理Docker证书与网络缓存 #

• 删除GHCR本地证书缓存，让Docker重新获取服务器证书：

  rm -rf ~/.docker/certs.d/ghcr.io
  

• 清理主机DNS缓存，避免解析异常：

  # Debian/Ubuntu
  systemd-resolve --flush-caches
  # RHEL/CentOS
  systemctl restart nscd
  

4. 优化主机资源配置 #

TLS握手需要消耗CPU/内存资源，若主机资源紧张会导致间歇性失败：

• 用top命令检查主机CPU、内存使用率
• 若资源不足，升级主机配置或减少同时运行的Runner任务数量，避免资源竞争

5. 手动指定GHCR登录凭证 #

绕过GitHub Actions自动登录逻辑，使用拥有read:packages权限的Personal Access Token（PAT）手动登录，稳定性更高：
修改工作流如下：

name: My Workflow
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: [selfhosted]
    steps:
      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GHCR_PAT }}
      - name: Run in container
        uses: docker://ghcr.io/myorg/myrepo/node:18
        with:
          args: echo "Hello"

注意：需在仓库Secrets中添加GHCR_PAT变量存储生成的PAT。

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