Skip to main content

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.

Hinweis: Dieser Pakettyp ist möglicherweise nicht für Ihre Instanz verfügbar, weil Websiteadministratoren die einzelnen unterstützten Pakettypen aktivieren oder deaktivieren können. Weitere Informationen findest du unter Konfigurieren der Paketökosystemunterstützung für dein Unternehmen.

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 Enterprise Server-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 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@REGISTRY_URL/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 , das bzw. die das Repository mit dem Gem besitzt.
  • REGISTRY_URL durch die URL der RubyGems-Registrierung deiner Instanz Wenn die Unterdomänenisolation für deine Instanz aktiviert ist, verwende rubygems.HOSTNAME. Wenn Unterdomänenisolation für deine Instanz deaktiviert ist, verwende HOSTNAME/_registry/rubygems. In beiden Fällen musst du HOSTNAME durch den Hostnamen deiner GitHub Enterprise Server-Instanz ersetzen.

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@REGISTRY_URL/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, das bzw. die das Repository besitzt, das das Gem enthält. Ersetze REGISTRY_URL durch die URL der RubyGems-Registrierung deiner Instanz. Wenn die Unterdomänenisolation für deine Instanz aktiviert ist, verwende rubygems.HOSTNAME. Wenn Unterdomänenisolation für deine Instanz deaktiviert ist, verwende HOSTNAME/_registry/rubygems. In beiden Fällen musst du HOSTNAME durch den Hostnamen deiner GitHub Enterprise Server-Instance ersetzen.

bundle config https://REGISTRY_URL/NAMESPACE USERNAME:TOKEN

Veröffentlichen eines Pakets

GitHub veröffentlicht das Paket standardmäßig in einem vorhandenen Repository mit demselben Namen wie das Paket. Wenn du GEM_NAME beispielsweise in der octo-org-Organisation veröffentlichen möchtest, veröffentlicht GitHub Packages das Gem im octo-org/GEM_NAME-Repository. Weitere Informationen zum Erstellen eines eigenen Gems findest du unter Erstellen eines eigenen Gems in der RubyGems-Dokumentation.

  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,das bzw. die das Repository besitzt, das in deinem Projekt enthalten ist, und GEM_NAME durch den Namen deines Gem-Pakets. Ersetze REGISTRY_URL durch die URL für die Rubygems-Registrierung deiner Instanz. Wenn die Unterdomänenisolation für deine Instanz aktiviert ist, verwende rubygems.HOSTNAME. Wenn Unterdomänenisolation für deine Instanz deaktiviert ist, verwende HOSTNAME/_registry/rubygems. In beiden Fällen musst du HOSTNAME durch den Hostnamen deiner GitHub Enterprise Server-Instance ersetzen.

    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://REGISTRY_URL/NAMESPACE \
    GEM_NAME-0.0.1.gem
    

Veröffentlichen mehrerer Pakete im gleichen Repository

Um mehrere Gems im selben Repository zu veröffentlichen, kannst du die URL zum GitHub-Repository in das Feld github_repo in gem.metadataeinfügen. Wenn du dieses Feld einschließt, gleicht GitHub das Repository basierend auf diesem Wert anstatt dem Gem-Namen ab. Ersetze HOSTNAME durch den Hostnamen von Ihre GitHub Enterprise Server-Instance.

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

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,das bzw. die das Repository besitzt, das das zu installierende Gem enthält. Ersetze REGISTRY_URL durch die URL der RubyGems-Registrierung deiner Instanz. Wenn die Unterdomänenisolation für deine Instanz aktiviert ist, verwende rubygems.HOSTNAME. Wenn Unterdomänenisolation für deine Instanz deaktiviert ist, verwende HOSTNAME/_registry/rubygems. In beiden Fällen musst du HOSTNAME durch den Hostnamen deiner GitHub Enterprise Server-Instance ersetzen.

    source "https://rubygems.org"
    
    gem "rails"
    
    source "https://REGISTRY_URL/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://REGISTRY_URL/NAMESPACE"
    source "https://rubygems.org"
    
    gem "rails"
    gem "GEM_NAME"
    
  4. Installiere das Paket:

    gem install GEM_NAME --version "0.1.1"
    

Weitere Informationsquellen