GHCR CLI 命令整理

约 605 字大约 2 分钟

2025-09-23

登录 GHCR

官方文档

Docker 登录

docker login ghcr.io

Username：你的 GitHub 用户名

Password：GitHub Personal Access Token (PAT)，需包含 read:packages（拉取）和 write:packages（推送）权限

成功登录后可以推送或拉取私有镜像

提示

生成 GitHub Personal Access Token（PAT），用于认证

步骤：

访问 GitHub 设置 → Developer settings → Personal access tokens → Fine-grained tokens
创建新 token，勾选 write:packages、read:packages、delete:packages 权限
保存 token（只显示一次）

通过官方安装包，访问 GitHub CLI Releases

gh --version

docker tag <本地镜像名>:<标签> ghcr.io/<用户名>/<仓库名>:<标签>

示例：

docker tag mynapp:1.0.0 ghcr.io/yumengjh/mynestapp:1.0.0

把本地镜像 mynapp:1.0.0 赋予远程 GHCR 地址标签，不会复制镜像，只是加标签引用

docker push ghcr.io/<用户名>/<仓库名>:<标签>

示例：

docker push ghcr.io/yumengjh/mynestapp:1.0.0

推送私有镜像需要先登录，公共镜像推送无需限制

docker pull ghcr.io/<用户名>/<仓库名>:<标签>

示例：

docker pull ghcr.io/yumengjh/mynestapp:1.0.0

拉取私有镜像需登录 GHCR，公共镜像无需登录

本地镜像：

docker images

远程 GHCR 镜像：需要 GitHub API 或 gh CLI

gh api -H "Accept: application/vnd.github+json" /user/packages/container

或者查看某个仓库：

gh api -H "Accept: application/vnd.github+json" /users/<用户名>/packages/container/<包名>/versions

GHCR 私有镜像默认私有，可以改为公共：

使用 GitHub CLI

gh api \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  /user/packages/container/<包名> \
  -f visibility=public

visibility=public → 设置为公开

visibility=private → 设置为私有

删除单个版本：

gh api \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  /user/packages/container/<包名>/versions/<version_id>

删除整个镜像包：

gh api \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  /user/packages/container/<包名>

注意：版本 ID 可以通过：

gh api /user/packages/container/<包名>/versions

查到。

GHCR 本身不支持直接改名，通常做法：

给原镜像打新标签：

docker tag ghcr.io/olduser/oldrepo:1.0 ghcr.io/newuser/newrepo:1.0

推送到新仓库：

docker push ghcr.io/newuser/newrepo:1.0

删除旧仓库（可选）

新版本更新：先 build 新镜像，然后打标签推送即可：

docker build -t mynapp:1.1.0 .
docker tag mynapp:1.1.0 ghcr.io/yumengjh/mynestapp:1.1.0
docker push ghcr.io/yumengjh/mynestapp:1.1.0

可以同时推 latest 标签：

docker tag mynapp:1.1.0 ghcr.io/yumengjh/mynestapp:latest
docker push ghcr.io/yumengjh/mynestapp:latest

版权归属：yumengjh