Utilisation du registre RubyGems

Prérequis

• Vous devez disposer de RubyGems 2.4.1 ou version ultérieure. Pour trouver votre version de RubyGems :

  gem --version
  

• Vous devez disposer de Bundler 1.6.4 ou version ultérieure. Pour trouver votre version de Bundler :

  $ bundle --version
  Bundler version 1.13.7
  

Authentification auprès de GitHub Packages

Vous avez besoin d’un jeton d’accès pour publier, installer et supprimer des packages privés, internes et publics.

Vous pouvez utiliser un personal access token (classic) pour vous authentifier sur GitHub Packages ou l’API GitHub Enterprise Server. Quand vous créez un personal access token (classic), vous pouvez l’attribuer à différentes étendues selon vos besoins. Pour plus d’informations sur les étendues liées aux packages pour un personal access token (classic), consultez « À propos des autorisations pour les packages GitHub ».

Pour vous authentifier sur un registre GitHub Packages dans un workflow GitHub Actions, vous pouvez utiliser :

• GITHUB_TOKEN pour publier des packages associés au dépôt du workflow.
• un personal access token (classic) avec au moins l’étendue read:packages pour installer des packages associés à d’autres dépôts privés (auxquels GITHUB_TOKEN ne peut pas accéder).

Authentification avec un personal access token

Vous devez utiliser un personal access token (classic) avec les étendues appropriées pour publier et installer des packages dans GitHub Packages. Pour plus d’informations, consultez « Introduction aux packages GitHub ».

Pour publier et installer des gemmes, vous pouvez configurer RubyGems ou Bundler pour qu’il s’authentifie auprès de GitHub Packages avec votre personal access token.

Pour publier de nouvelles gemmes, vous devez vous authentifier auprès de GitHub Packages avec RubyGems en modifiant votre fichier ~/.gem/credentials afin d’inclure votre personal access token (classic). Créez un fichier ~/.gem/credentials si ce fichier n’existe pas.

Par exemple, vous créez ou modifiez un fichier ~/.gem/credentials pour inclure les éléments suivants, en remplaçant TOKEN par votre personal access token.

---
:github: Bearer TOKEN

Pour installer des gemmes, vous devez vous authentifier auprès de GitHub Packages en mettant à jour vos sources de gemme pour inclure https://USERNAME:TOKEN@REGISTRY_URL/NAMESPACE/. Vous devez remplacer :

• USERNAME par votre nom d’utilisateur GitHub.
• TOKEN par votre personal access token (classic).
• NAMESPACE par le nom du compte personnel ou de l’organisation propriétaire du dépôt contenant la gemme.
• REGISTRY_URL par l’URL du registre Rubygems de votre instance. Si l’isolation de sous-domaine est activée pour votre instance, utilisez rubygems.HOSTNAME. Si l’isolation de sous-domaine est désactivée pour votre instance, utilisez HOSTNAME/_registry/rubygems. Dans les deux cas, remplacez HOSTNAME par le nom d’hôte de votre instance GitHub Enterprise Server.

Si vous souhaitez que votre package soit disponible globalement, vous pouvez exécuter la commande suivante pour ajouter votre registre en tant que source.

gem sources --add https://USERNAME:TOKEN@REGISTRY_URL/NAMESPACE/

Pour vous authentifier auprès de Bundler, configurez Bundler pour utiliser votre personal access token (classic), en remplaçant USERNAME par votre nom d’utilisateur GitHub, TOKEN par votre personal access token et NAMESPACE par le nom du compte personnel ou de l’organisation propriétaire du dépôt contenant la gemme. Remplacez REGISTRY_URL par l’URL du registre RubyGems de votre instance. Si l’isolation de sous-domaine est activée pour votre instance, utilisez rubygems.HOSTNAME. Si l’isolation de sous-domaine est désactivée pour votre instance, utilisez HOSTNAME/_registry/rubygems. Dans les deux cas, remplacez HOSTNAME par le nom d’hôte de votre instance GitHub Enterprise Server.

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

Publication d’un package

Par défaut, GitHub publie le package dans un dépôt existant portant le même nom que le package. Par exemple, lorsque vous publiez GEM_NAME dans l’organisation octo-org, GitHub Packages publie la gemme dans le dépôt octo-org/GEM_NAME. Pour plus d’informations sur la création de votre gemme, consultez « Créer votre propre gemme » dans la documentation de RubyGems.

1. Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez « Authentification auprès de GitHub Packages ».

2. Générez le package à partir de gemspec pour créer le package .gem . Remplacez GEM_NAME par le nom de votre gemme.

   gem build GEM_NAME.gemspec
   

3. Publiez un package sur GitHub Packages, en remplaçant NAMESPACE par le nom du compte personnel ou de l’organisation propriétaire du dépôt contenant votre projet et GEM_NAME par le nom de votre package gem. Remplacez REGISTRY_URL par l’URL du registre Rubygems de votre instance. Si l’isolation de sous-domaine est activée pour votre instance, utilisez rubygems.HOSTNAME. Si l’isolation de sous-domaine est désactivée pour votre instance, utilisez HOSTNAME/_registry/rubygems. Dans les deux cas, remplacez HOSTNAME par le nom d’hôte de votre instance GitHub Enterprise Server.

   Remarque : La taille maximale non compressée du fichier metadata.gz d’une gemme doit être inférieure à 2 Mo. Les demandes de poussée de gemmes qui dépassent cette limite échouent.

   $ gem push --key github \
   --host https://REGISTRY_URL/NAMESPACE \
   GEM_NAME-0.0.1.gem
   

Publication de plusieurs packages sur le même dépôt

Pour publier plusieurs gemmes dans le même dépôt, vous pouvez inclure l’URL du dépôt GitHub dans le champ github_repo dans gem.metadata. Si vous incluez ce champ, GitHub établit une correspondance avec le dépôt en fonction de cette valeur, au lieu d'utiliser le nom de la gemme. Remplacez HOSTNAME par le nom d'hôte de votre instance GitHub Enterprise Server.

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

Installation d’un package

Vous pouvez utiliser des gemmes à partir de GitHub Packages de la même façon que vous utilisez des gemmes de rubygems.org. Vous devez vous authentifier auprès de GitHub Packages en ajoutant votre utilisateur ou votre organisation GitHub en tant que source dans le fichier ~/.gemrc, ou en utilisant Bundler et en modifiant votre gemfile.

1. Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez « Authentification auprès de GitHub Packages ».

2. Pour Bundler, ajoutez votre utilisateur ou organisation GitHub en tant que source dans votre Gemfile pour extraire des gemmes de cette nouvelle source. Par exemple, vous pouvez ajouter un nouveau bloc source à votre Gemfile qui utilise GitHub Packages uniquement pour les packages que vous spécifiez, en remplaçant GEM_NAME par le package que vous souhaitez installer à partir de GitHub Packages et NAMESPACE par le compte personnel ou l’organisation propriétaire du dépôt contenant la gemme que vous souhaitez installer. Remplacez REGISTRY_URL par l’URL du registre Rubygems de votre instance. Si l’isolation de sous-domaine est activée pour votre instance, utilisez rubygems.HOSTNAME. Si l’isolation de sous-domaine est désactivée pour votre instance, utilisez HOSTNAME/_registry/rubygems. Dans les deux cas, remplacez HOSTNAME par le nom d’hôte de votre instance GitHub Enterprise Server.

   source "https://rubygems.org"
   
   gem "rails"
   
   source "https://REGISTRY_URL/NAMESPACE" do
     gem "GEM_NAME"
   end
   

3. Pour les versions de Bundler antérieures à 1.7.0, vous devez ajouter une nouvelle source globale. Pour plus d’informations sur l’utilisation de Bundler, consultez la documentation de bundler.io.

   source "https://REGISTRY_URL/NAMESPACE"
   source "https://rubygems.org"
   
   gem "rails"
   gem "GEM_NAME"
   

4. Installez le package :

   gem install GEM_NAME --version "0.1.1"
   

Pour aller plus loin

• « Suppression et restauration d'un package »