Skip to main content

GHCR 登入與 Token 權限設定教學（Docker Login）

Summary​

這篇教學說明如何安全登入 ghcr.io，並用最小權限建立可用的 GitHub Token（PAT）。

適用情境：

  • 本機或 CI 需要 docker pull 私有映像
  • 需要 docker push 發佈映像到 GHCR
  • 需要避免給過大權限造成資安風險

Prerequisites​

  • 有 GitHub 帳號
  • 目標 Repository / Package 你有對應存取權
  • 已安裝 Docker CLI

Step-by-step​

Step 1：建立 Token（PAT classic）​

到 GitHub 建立 Personal access token (classic)，並依需求勾選權限：

  • 只讀取 package：read:packages
  • 推送 package：write:packages
  • 刪除 package（可選）：delete:packages
  • 若需存取 private repo 關聯 package：加 repo

建議：先從最小權限開始，不夠再補，不要一次全開。

Step 2：把 Token 存成環境變數​

export GHCR_TOKEN='你的token'

Step 3：登入 GHCR（推薦用 stdin）​

echo "$GHCR_TOKEN" | docker login ghcr.io -u <github-username> --password-stdin

成功會看到 Login Succeeded。

Step 4：驗證 pull / push​

只讀測試（pull）​

docker pull ghcr.io/<owner>/<image>:<tag>

推送測試（push）​

docker tag <local-image>:<tag> ghcr.io/<owner>/<image>:<tag>
docker push ghcr.io/<owner>/<image>:<tag>

Validation​

檢查點：

  • docker login ghcr.io 成功
  • docker pull 可成功拉取（只讀 token）
  • docker push 可成功推送（寫入 token）
  • 在 GitHub Packages 頁面可看到新 tag（若有 push）

Troubleshooting​

denied: permission_denied​

  • Token scope 不足，補 read:packages 或 write:packages
  • 目標 package 屬於 private，確認 token 是否有 repo

unauthorized: authentication required​

  • Token 過期/輸入錯誤
  • username 不是 GitHub 帳號名稱
  • shell 變數未正確載入

可以登入但 pull 不到 private image​

  • 確認該帳號對 repo/package 有讀取權限
  • 若 package 與 repo 綁定，權限以 repo 存取為準

Security checklist​

  • Token 不寫死在程式碼或 YAML
  • CI 使用 Secrets 管理 token
  • 優先使用最小權限
  • 定期輪替 token
  • 離職/權限變更時立即失效舊 token

References​

  • GitHub Docs: Working with the Container registry (GHCR)
  • GitHub Docs: Creating a personal access token (classic)