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 push
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: |
${{ secrets.REGISTRY_URL }}/myproject/app:${{ github.sha }}
${{ secrets.REGISTRY_URL }}/myproject/app:latest
cache-from: type=gha
cache-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组中
简化多环境部署（可选）
如果需要按分支/标签推送到不同 namespace，可用变量动态生成 tag：
- 用
${{ github.head_ref || github.ref_name }}区分 dev/staging/prod 分支 - 对 release tag（如
v1.2.3）额外打 semantic version 标签 - 配合
if条件控制是否推送 latest，避免覆盖不稳定版本
