RubyGems 導覽選單
指南

RubyGems.org API 金鑰、其範圍和 CLI 使用

你可以根據你的需求建立多個 API 金鑰。API 金鑰有不同的範圍，授予特定的權限。使用權限最少的 API 金鑰，可以透過限制受損金鑰可能造成的影響，讓你的 RubyGems.org 帳戶更安全。

建立新的 API 金鑰

拜訪你的 RubyGems.org 帳戶 設定頁面，然後按一下API 金鑰。系統會提示你輸入帳戶密碼以確認你的身分。

Settings API key

如果你之前從未拜訪過此頁面，你應該會看到至少一個名為legacy-key的金鑰。legacy-key是 RubyGems.org 過去為每個帳戶使用單一 API 金鑰且具有完全存取權限的遺跡。我們建議你盡快從legacy-key遷移。

按一下新的 API 金鑰，為你的帳戶建立新的 API 金鑰。

Settings API key

輸入一個名稱，以協助您識別 API 金鑰可能用於的環境（例如：ci-push-key、mirror-webhook-key 等）。勾選您可能想要啟用的所有範圍，然後按一下「建立」。

注意：顯示儀表板是一個獨占範圍，且無法與任何其他範圍合併啟用。

New API key

在以下頁面上，您應該會看到新的 API 金鑰。

API key created

年齡欄位會顯示金鑰的年齡。上次存取欄位會顯示金鑰在成功驗證中使用時的上一次時間（UTC）。您可以使用編輯按鈕來更新金鑰的範圍。您可以在最後一列使用重設按鈕來刪除與您的帳戶關聯的所有 API 金鑰。

與 gem CLI 搭配使用

如上所述建立的 API 金鑰可直接在 gem CLI 中使用，方法是在稱為 GEM_HOST_API_KEY 的環境變數中設定它，例如：

$ GEM_HOST_API_KEY=rubygems_123456 gem push example-1.2.3.gem

此方法適用於非互動式情況，例如用於基於 CI/CD 的 gem 發布流程。在您可以直接存取的個人開發機器上，通常較建議使用 gem signin 進行互動式登入（請見下方）。

從 gem CLI 建立

注意：如果您想使用 gem CLI 的範圍建立 API 金鑰，您需要 rubygems 3.2.0 或更新版本。

執行 gem signin 會提示您輸入您的 RubyGems.org 認證資料、金鑰名稱，以及要為金鑰啟用的範圍。所有範圍的預設選項都是不啟用它們。

$ gem signin
Enter your RubyGems.org credentials.
Don't have an account yet? Create one at https://rubygems.org/sign_up
   Email:   john@doe.com
Password:

API Key name [4458ffe32b0c-unknown-user-20201231104303]:   docker-push-key
Please select scopes you want to enable for the API key (y/n)
index_rubygems [y/N]:
push_rubygem [y/N]:   Y
yank_rubygem [y/N]:
add_owner [y/N]:
remove_owner [y/N]:
access_webhooks [y/N]:
show_dashboard [y/N]:

Signed in with API key: docker-push-key.

當我們在您的主機上找不到任何 API 金鑰時，將會自動建立一個 API 金鑰（預設金鑰名稱：hostname-whoami-timestamp）並具有所需的範圍。類似地，如果金鑰沒有正確的範圍，主機上現有 API 金鑰的範圍將會使用所需的範圍更新。

$ gem yank begone -v 4.1.48
Yanking gem from https://rubygems.org...
The existing key doesn't have access of yank_rubygem on https://rubygems.org. Please sign in to update access.
   Email:   john@doe.com
Password:
Added yank_rubygem scope to the existing API key
Successfully deleted gem: begone (4.1.48)

API 金鑰範圍

  • 索引 rubygems：列出您帳戶中的所有 RubyGems
  • 推播 rubygems：建立新的 RubyGem 或發布您擁有的任何 RubyGem 的新版本
  • 撤回 rubygems：移除您擁有的任何 RubyGem 的已發布版本
  • 新增擁有者：將使用者新增為您擁有的任何 RubyGem 的擁有者
  • 移除擁有者：從您擁有的任何 RubyGem 的擁有者中移除使用者
  • 存取網路掛鉤：列出、建立、刪除或觸發與您的帳戶關聯的網路掛鉤
  • 顯示儀表板：存取您的 RubyGems.org 儀表板的 atom feed。這是一個獨占範圍，且無法與任何其他範圍合併啟用。

在特定 API 金鑰上啟用多重身分驗證

如果你的帳戶僅在使用者介面或使用者介面和 gem 登入驗證層級啟用多重驗證，你可以選擇在特定 API 金鑰上啟用多重驗證。這將需要 gem push、yank、owner --add/--remove 指令的 OTP 驗證碼。

你可以在使用者介面上建立或編輯 API 金鑰時切換此選項。已啟用多重驗證的新 API 金鑰

從舊版 API 金鑰遷移

你的帳戶的舊版 API 金鑰已遷移到啟用所有範圍的 API 金鑰。我們強烈建議你刪除此金鑰，並以啟用最小範圍的新 API 金鑰取代它。

  • 前往帳戶的API 金鑰頁面，並按一下名稱為legacy-key的金鑰的刪除按鈕。
  • 在你已使用舊版 API 金鑰的所有主機上執行 gem signout
  • 請確定你已安裝 rubygems 3.2.0 或更新版本。執行 gem update --system 將你的 rubygem 更新至最新版本。
  • 執行 gem signin 以建立新的 API 金鑰。

如果你無法更新你的 rubygems，你仍可以使用新的 API 金鑰，方法是使用網路使用者介面建立新的金鑰，並取代 ~/.gem/credentials 或 ~/.local/share/gem/credentials 檔案中的金鑰。

$ cat ~/.local/share/gem/credentials
:rubygems_api_key: rubygems_cec9db9373ea171daaaa0bf2337edce187f09558cb19c1b2

注意：擷取 API 金鑰的舊版端點 GET /api/v1/keys 已更新為在每個請求上建立新的 API 金鑰。作為安全防護措施，新的 API 金鑰會在單向加密後儲存在我們的資料庫中。我們不再能夠以純文字擷取相同的 API 金鑰。

上一個 下一個