Arbeiten mit der RubyGems-Registrierung

Du kannst RubyGems so konfigurieren, dass ein Paket in GitHub Packages veröffentlicht wird und Pakete verwendet werden, die in GitHub Packages als Abhängigkeiten in einem Ruby-Projekt mit Bundler gespeichert sind.

Wer kann dieses Feature verwenden?

GitHub Packages ist verfügbar mit GitHub Free, GitHub Pro, GitHub Free für Organisationen, GitHub Team, GitHub Enterprise Cloud und GitHub Enterprise Server 3.0 oder höher.

In diesem Artikel

URL für die RubyGems-Registrierung

Wenn du auf GitHub unter GitHub.com zugreifst, veröffentlichst du Pakete in https://rubygems.pkg.github.com. In den Beispielen in diesem Artikel wird diese URL verwendet.

Wenn du auf GitHub in einer anderen Domäne zugreifst, z. B. octocorp.ghe.com, ersetzt du „https://rubygems.pkg.github.com“ durch https://rubygems.SUBDOMAIN.ghe.com, wobei SUBDOMAIN die eindeutige Unterdomäne deines Unternehmens ist.

Voraussetzungen

  • Du musst über RubyGems 2.4.1 oder höher verfügen. So ermittelst du deine RubyGems-Version:

    gem --version

  • Du musst über Bundler 1.6.4 oder höher verfügen. So ermittelst du deine Bundler-Version:

    $ bundle --version
Bundler version 1.13.7

Bei GitHub Packages authentifizieren

GitHub Packages unterstützt nur die Authentifizierung mit einem personal access token (classic). Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken.

Du benötigst ein Zugriffstoken, um private, interne und öffentliche Pakete zu veröffentlichen, zu installieren und zu löschen.

Du kannst ein personal access token (classic) für die Authentifizierung bei GitHub Packages oder bei der GitHub-API verwenden. Wenn du ein personal access token (classic) erstellst, kannst du dem Token je nach Bedarf verschiedene Bereiche zuweisen. Weitere Informationen zu paketbezogenen Bereichen für ein personal access token (classic) findest du unter Informationen zu Berechtigungen für GitHub-Pakete.

Um dich bei einer GitHub Packages-Registrierung innerhalb eines GitHub Actions-Workflows zu authentifizieren, kannst du Folgendes verwenden:

  • GITHUB_TOKEN, um Pakete zu veröffentlichen, die mit dem Workflowrepository verbunden sind.
  • Ein personal access token (classic) (diesem muss mindestens der Bereich read:packages zugeordnet sein), um Pakete zu installieren, die zu anderen privaten Repositorys gehören (auf die GITHUB_TOKEN nicht zugreifen kann)

Authentifizieren in einem GitHub Actions-Workflow

Diese Registrierung unterstützt präzise Berechtigungen. Wenn dein GitHub Actions-Workflow ein personal access token zum Authentifizieren bei einer Registrierung verwendet, solltest du für Registrierungen, die differenzierte Berechtigungen unterstützen, deinen Workflow unbedingt so aktualisieren, dass das GITHUB_TOKEN verwendet wird. Eine Anleitung zum Aktualisieren deiner Workflows, die sich mit einem personal access token bei einer Registrierung authentifizieren, findest du unter Veröffentlichen und Installieren eines Pakets mit GitHub Actions.

Hinweis: Die Möglichkeit für GitHub Actions-Workflows, Pakete mithilfe der REST-API zu löschen und wiederherzustellen, befindet sich derzeit in der public preview und kann noch geändert werden.

Sie können ein GITHUB_TOKEN in einem GitHub Actions-Workflow verwenden, um ein Paket mithilfe der REST-API zu löschen oder wiederherzustellen, wenn das Token über die admin-Berechtigung für das Paket verfügt. Repositorys, die Pakete mithilfe eines Workflows veröffentlichen, und Repositorys, die du explizit mit Paketen verbunden hast, erhalten automatisch die admin-Berechtigung für Pakete im Repository.

Weitere Informationen zum GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu den Best Practices bei der Verwendung einer Registrierung in Actions findest du unter Sicherheitshärtung für GitHub Actions.

Du kannst außerdem auswählen, ob du Zugriffsberechtigungen auf Pakete unabhängig voneinander für GitHub Codespaces und GitHub Actions erteilen möchtest. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen und unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.

Authentifizieren mit einem personal access token

Du musst ein personal access token (classic) mit den entsprechenden Bereichen verwenden, um Pakete in GitHub Packages zu veröffentlichen und zu installieren. Weitere Informationen findest du unter Einführung in GitHub-Pakete.

Zum Veröffentlichen und Installieren von Gems kannst du RubyGems oder Bundler für die Authentifizierung bei GitHub Packages mithilfe eines personal access token konfigurieren.

Um neue Gems zu veröffentlichen, musst du dich mit RubyGems bei GitHub Packages authentifizieren, indem du dein personal access token (classic) in die Datei ~/.gem/credentials einfügst. Erstelle eine neue Datei ~/.gem/credentials, falls sie noch nicht vorhanden ist.

Du kannst beispielsweise die Datei ~/.gem/credentials so erstellen oder bearbeiten, dass sie Folgendes enthält, und dabei TOKEN durch dein personal access token ersetzen.

---
:github: Bearer TOKEN

Um Gems zu installieren, musst du dich bei GitHub Packages authentifizieren, indem du deine Gem-Quellen so aktualisierst, dass sie https://USERNAME:TOKEN@rubygems.pkg.github.com/NAMESPACE/ enthalten. Dabei musst du Folgendes ersetzen:

  • USERNAME durch deinen GitHub-Benutzernamen
  • TOKEN durch dein personal access token (classic)
  • NAMESPACE mit dem Namen des persönlichen Kontos oder der Organisation , auf das bzw. die das Gem ausgerichtet ist besitzt.

Wenn dein Paket global verfügbar sein soll, kannst du den folgenden Befehl ausführen, um deine Registrierung als Quelle hinzuzufügen.

gem sources --add https://USERNAME:TOKEN@rubygems.pkg.github.com/NAMESPACE/

Um sich mit Bundler zu authentifizieren, musst du Bundler für die Verwendung deines personal access token (classic) konfigurieren, indem du USERNAME durch deinen GitHub-Benutzernamen, TOKEN durch dein personal access token und NAMESPACE durch den Namen des persönlichen Kontos oder der Organisation ersetzt, auf das bzw. die das Gem ausgerichtet ist.

bundle config https://rubygems.pkg.github.com/NAMESPACE USERNAME:TOKEN

Veröffentlichen eines Pakets

Wenn du ein Paket zum ersten Mal veröffentlichst, ist die Sichtbarkeit standardmäßig auf privat eingestellt. Informationen zum Ändern der Sichtbarkeit oder zum Festlegen von Zugriffsberechtigungen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen. Weitere Informationen zum Erstellen eines eigenen Gems findest du unter Erstellen eines eigenen Gems in der RubyGems-Dokumentation.

Hinweis: Wenn du ein Paket veröffentlichst, das mit einem Repository verknüpft ist, erbt das Paket automatisch die Zugriffsberechtigungen des verknüpften Repositorys, und GitHub Actions-Workflows im verknüpften Repository erhalten automatisch Zugriff auf das Paket, es sei denn, deine Organisation hat die automatische Vererbung von Zugriffsberechtigungen deaktiviert. Weitere Informationen findest du unter Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.

  1. Authentifizieren bei GitHub Packages. Weitere Informationen findest Du unter Authentifizieren bei GitHub Packages.

  2. Erstelle das Paket aus gemspec, um das GEM-Paket zu erstellen. Ersetze GEM_NAME durch den Namen deines Gems.

    gem build GEM_NAME.gemspec

  3. Veröffentliche ein Paket in GitHub Packages, und ersetze NAMESPACE durch den Namen deines persönlichen Kontos oder deiner Organisation,auf das bzw. die das Paket ausgerichtet werden soll, und GEM_NAME durch den Namen deines Gem-Pakets.

    Hinweis: Die maximale unkomprimierte Größe der metadata.gz-Datei eines Gems muss weniger als 2 MB betragen. Anforderungen zum Pushen von Gems, die diesen Grenzwert überschreiten, schlagen fehl.

    $ gem push --key github \
--host https://rubygems.pkg.github.com/NAMESPACE \
GEM_NAME-0.0.1.gem

Verbinden eines Pakets mit einem Repository

Die RubyGems-Registrierung speichert Pakete in deinem Organisationskonto oder in deinem persönlichen Konto und ermöglicht die Zuordnung von Paketen zu einem Repository. Du kannst wählen, ob Berechtigungen von einem Repository geerbt oder präzise Berechtigungen unabhängig von einem Repository festgelegt werden sollen.

Du kannst sicherstellen, dass Gems mit einem Repository verknüpft werden, sobald sie veröffentlicht werden, indem du die URL des GitHub-Repositorys in das github_repo-Feld in gem.metadata einfügst. Du kannst mehrere Gems mit demselben Repository verknüpfen.

gem.metadata = { "github_repo" => "ssh://github.com/OWNER/REPOSITORY" }

Informationen zum Verknüpfen eines veröffentlichten Pakets mit einem Repository findest du unter Verbinden eines Repositorys mit einem Paket.

Installieren eines Pakets

Du kannst Gems aus GitHub Packages in etwa so wie Gems von rubygems.org verwenden. Du musst dich bei GitHub Packages authentifizieren, indem du dein GitHub-Benutzerkonto oder deine -Organisation als Quelle in der Datei ~/.gemrc oder durch Bearbeitung deiner Gemfile mithilfe von Bundler hinzufügst.

  1. Authentifizieren bei GitHub Packages. Weitere Informationen findest Du unter Authentifizieren bei GitHub Packages.

  2. Für Bundler kannst du dein GitHub -Benutzerkonto bzw. deine -Organisation als Quelle zu deiner Gemfile-Datei hinzufügen, um Gems aus dieser neuen Quelle abrufen. Du kannst deinem Gemfile beispielsweise einen neuen source-Block hinzufügen, der GitHub Packages nur für die von dir angegebenen Pakete verwendet. Dazu musst du GEM_NAME durch das Paket ersetzen, das du aus GitHub Packages installieren möchtest, und NAMESPACE durch das persönliche Konto oder die Organisation,für das bzw. die das Gem, das du installieren möchtest, festgelegt wurde

    source "https://rubygems.org"

gem "rails"

source "https://rubygems.pkg.github.com/NAMESPACE" do
  gem "GEM_NAME"
end

  3. Für Bundler-Versionen, die älter als 1.7.0 sind, musst du eine neue globale Quelle (source) hinzufügen. Weitere Informationen zur Verwendung von Bundler findest du in der Dokumentation zu bundler.io.

    source "https://rubygems.pkg.github.com/NAMESPACE"
source "https://rubygems.org"

gem "rails"
gem "GEM_NAME"

  4. Installiere das Paket:

    gem install GEM_NAME --version "0.1.1"

Weitere Informationsquellen