GHCR（GitHub Container Registry）全面介绍

在现代云原生与 DevOps 体系中，容器镜像已经成为应用交付的核心资产。

过去开发者通常会把 Docker 镜像推送到 Docker Hub，但随着企业对权限控制、私有化、安全扫描、CI/CD 集成需求越来越高，GitHub 推出了自己的容器镜像仓库：

👉 GHCR（GitHub Container Registry）

它是 GitHub Packages 生态中的容器镜像服务，可以直接与 GitHub 仓库、Actions、权限系统深度集成。

本文将全面介绍 GHCR 的概念、架构、工作方式、优势以及实际使用方法。

---

一、什么是 GHCR？

GHCR 全称：

GitHub Container Registry

它是 GitHub 提供的 OCI（Open Container Initiative）兼容容器镜像仓库。

简单理解：

GitHub = 代码仓库
GHCR = 镜像仓库

你可以把：

• Docker 镜像
• OCI 镜像
• Helm Chart（OCI 模式）
• Build Artifact

存储到 GHCR。

---

二、GHCR 的官方地址

GHCR 的镜像域名：

ghcr.io

例如：

ghcr.io/my-org/my-app:latest

这就是一个标准的 GHCR 镜像地址。

---

三、GHCR 与 Docker Hub 的区别

对比项	GHCR	Docker Hub
所属平台	GitHub	Docker
与代码仓库关联	极强	一般
GitHub Actions 集成	原生支持	需要额外配置
权限继承	GitHub 权限体系	Docker Hub 权限
OCI 支持	完整	完整
私有仓库体验	更优秀	部分功能收费
企业生态	GitHub Enterprise	Docker Business
镜像命名	ghcr.io/org/image	docker.io/user/image

---

四、GHCR 的核心优势

1. 与 GitHub 深度集成

这是 GHCR 最大的优势。

例如：

• GitHub Actions 自动发布镜像
• PR 自动构建镜像
• Release 自动打 Tag
• 权限直接继承 GitHub Organization

开发体验非常丝滑。

---

2. 权限控制强大

GHCR 使用 GitHub 的权限模型：

• Organization
• Team
• Repository
• Personal Account

例如：

只有 backend-team 可以 pull
只有 ci-bot 可以 push

企业管理会非常方便。

---

3. 原生支持 OCI 标准

OCI 是现代容器生态标准。

GHCR 不仅支持：

• Docker Image

还支持：

• OCI Artifact
• Helm OCI
• SBOM
• 签名元数据

这对于供应链安全非常重要。

---

4. GitHub Actions 无缝 CI/CD

这是最常见的场景。

例如：

- name: Login to GHCR
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

- name: Build and Push
  uses: docker/build-push-action@v5
  with:
    push: true
    tags: ghcr.io/my-org/my-app:latest

直接即可完成：

代码提交 → Actions → 自动构建 → 自动推送 GHCR

---

五、GHCR 的工作流程

典型流程：

开发者提交代码
        ↓
GitHub Actions 自动构建
        ↓
生成 Docker Image
        ↓
Push 到 ghcr.io
        ↓
Kubernetes 拉取镜像
        ↓
应用部署

---

六、GHCR 镜像命名规则

GHCR 的标准格式：

ghcr.io/<OWNER>/<IMAGE>:<TAG>

例如：

ghcr.io/acme/payment-service:v1.0.0

说明：

部分	含义
ghcr.io	Registry 域名
acme	GitHub 用户或组织
payment-service	镜像名
v1.0.0	Tag

---

七、如何登录 GHCR

使用 Docker Login

docker login ghcr.io

用户名：

GitHub 用户名

密码：

GitHub Personal Access Token（PAT）

注意：

GitHub 已不支持使用账户密码登录。

---

八、PAT Token 权限

常见权限：

权限	作用
read:packages	拉取镜像
write:packages	推送镜像
delete:packages	删除镜像

---

九、推送镜像到 GHCR

1. 构建镜像

docker build -t my-app .

---

2. 打 Tag

docker tag my-app ghcr.io/my-org/my-app:v1

---

3. Push

docker push ghcr.io/my-org/my-app:v1

完成后即可在 GitHub Packages 页面看到镜像。

---

十、从 GHCR 拉取镜像

公开镜像：

docker pull ghcr.io/my-org/my-app:v1

私有镜像：

需要先登录：

docker login ghcr.io

---

十一、GHCR 与 Kubernetes

Kubernetes 非常适合搭配 GHCR。

例如：

containers:
  - name: app
    image: ghcr.io/acme/api:v1

私有镜像通常需要：

imagePullSecrets:
  - name: ghcr-secret

---

十二、GitHub Actions 自动发布镜像

这是 GHCR 最经典用法。

示例 Workflow

name: Build Image

on:
  push:
    branches:
      - main

jobs:
  docker:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Login GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/my-org/my-app:latest

---

十三、GHCR 的权限模型

GHCR 支持：

1. Public Package

任何人都能 pull。

适合：

• 开源项目
• 公共镜像

---

2. Private Package

只有授权用户可访问。

适合：

• 企业内部服务
• 私有平台

---

3. Internal Package（企业版）

企业内部所有成员可访问。

---

十四、GHCR 与 Helm OCI

GHCR 不仅能存 Docker 镜像。

还支持：

Helm Chart OCI Registry

例如：

helm push mychart-0.1.0.tgz oci://ghcr.io/my-org/charts

这已经成为现代 Helm 推荐方式。

---

十五、GHCR 与供应链安全

GHCR 非常适合现代软件供应链体系。

例如：

• 镜像签名
• SBOM（软件物料清单）
• provenance
• cosign
• SLSA（供应链级别工件认证）

未来容器安全生态基本都会围绕 OCI Artifact 展开。

---

十六、GHCR 的常见使用场景

开源项目

GitHub 仓库 + GHCR 发布镜像

例如：

ghcr.io/kubernetes/dashboard

---

企业内部平台

CI/CD → GHCR → Kubernetes

形成完整交付链路。

---

多环境部署

ghcr.io/acme/app:dev
ghcr.io/acme/app:staging
ghcr.io/acme/app:prod

---

十七、GHCR 的最佳实践

1. Tag 不要只用 latest

推荐：

v1.0.0
v1.0
commit-sha

---

2. 使用 Immutable Tag（Immutable Tag（不可变标签） 是指在 Docker 容器镜像管理中，使用不会被覆盖的标签来标识镜像版本的实践。与之相对的是 latest 这样的可变标签，它会被新的构建覆盖，导致版本追踪困难。）

避免：

latest 被覆盖

导致线上不可追踪。

---

3. 配合 Git SHA

例如：

ghcr.io/acme/app:sha-8f3a2d1

方便回滚。

---

4. 开启镜像签名

推荐：

• cosign（联署）
• sigstore（签名存储）

---

5. 使用多阶段构建

减小镜像体积：

FROM golang:1.24 AS builder

FROM alpine:3.20

---

十八、GHCR 的局限性

虽然 GHCR 很优秀，但也有一些问题。

1. UI 不如 Docker Hub 直观

镜像浏览体验一般。

---

2. 跨平台生态不如 Docker Hub 普及

很多教程默认仍使用 Docker Hub。

---

3. 企业复杂权限需要规划

大型 Organization 下：

• Team
• Repo
• Package

关系可能变复杂。

---

十九、GHCR 在现代云原生中的地位

如今很多团队已经形成：

GitHub
   ↓
GitHub Actions
   ↓
GHCR
   ↓
Kubernetes

完整 DevOps 闭环。

尤其对于：

• 小团队
• 开源项目
• GitHub 重度用户

GHCR 几乎是最佳选择之一。

---

二十、总结

GHCR 本质上是：

GitHub 官方提供的 OCI 容器镜像仓库

它最大的价值在于：

代码 + CI/CD + 镜像仓库
统一在 GitHub 生态中

核心优势：

• GitHub Actions 原生集成
• 权限体系统一
• 支持 OCI 标准
• 支持 Helm OCI
• 云原生友好
• 企业 DevOps 体验优秀

对于现代 Kubernetes 与云原生体系而言：

GHCR 已经不仅仅是“镜像仓库”。

它正在成为：

GitHub 云原生交付平台的重要组成部分