GitHub Actions 如何上传镜像到私有镜像仓库

作者：袖梨 2026-07-08

GitHub Actions上传镜像到私有仓库的核心是登录→构建→推送，关键在于通过Secrets安全配置REGISTRY_USERNAME、REGISTRY_PASSWORD和REGISTRY_URL，并使用docker/login-action与build-push-action完成认证与推送，需确保网络可达、权限正确及镜像命名含完整registry前缀。

GitHub Actions 上传镜像到私有镜像仓库，核心是：登录私有仓库 → 构建镜像 → 推送镜像。关键在于正确配置认证、避免暴露凭据、适配私有仓库地址和端口。

配置私有仓库访问凭证

不能把账号密码硬编码在 workflow 文件里。推荐用 GitHub Secrets 存储敏感信息：

在仓库 Settings → Secrets and variables → Actions 中添加：
REGISTRY_USERNAME（如 admin）
REGISTRY_PASSWORD（如对应密码或 token）
REGISTRY_URL（如 harbor.example.com 或带端口的 registry.internal:5000）
若私有仓库使用自签名证书，还需在 job 中提前信任证书（例如挂载 CA 证书并配置 Docker daemon），否则 docker login 会失败。

编写 workflow 实现构建与推送

以推送镜像到 harbor.example.com/myproject/app 为例，典型步骤如下：

使用 docker/login-action 登录私有仓库（支持 username/password 或 token）
用 docker/build-push-action 构建并直接推送，指定 push: true 和 tags
镜像名需完整包含 registry 地址，例如：${{ secrets.REGISTRY_URL }}/myproject/app:${{ github.sha }}

示例片段：

steps:  - name: Login to private registry    uses: docker/login-action@v3    with:      registry: ${{ secrets.REGISTRY_URL }}      username: ${{ secrets.REGISTRY_USERNAME }}      password: ${{ secrets.REGISTRY_PASSWORD }}<ul><li>name: Build and pushuses: docker/build-push-action@v5with:context: .push: truetags: |${{ secrets.REGISTRY_URL }}/myproject/app:${{ github.sha }}${{ secrets.REGISTRY_URL }}/myproject/app:latestcache-from: type=ghacache-to: type=gha,mode=max

处理常见问题

遇到推送失败时，优先检查以下几点：

网络连通性：GitHub 托管的 runner 默认无法访问内网 registry；必须使用 self-hosted runner 部署在可访问私有仓库的网络中
仓库权限：确认 REGISTRY_USERNAME 在目标项目（如 Harbor 的 project）中有 push 权限
镜像命名规范：私有仓库通常要求镜像名含完整 registry 前缀，且 project 名需已存在，否则推送会 404 或 403
Docker daemon 状态：self-hosted runner 上确保 docker service 正常运行，且 runner 用户在 docker 组中