Utilisation du registre RubyGems

Dans cet article

Vous pouvez configurer RubyGems pour qu’il publie un package dans GitHub Packages et utilise les packages stockés dans GitHub Packages comme dépendances dans un projet Ruby avec Bundler.

GitHub Packages est disponible avec GitHub Free, GitHub Pro, GitHub Free pour les organisations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 ou ultérieur et GitHub AE.
GitHub Packages n’est pas disponible pour les référentiels privés appartenant à des comptes qui utilisent des plans par référentiel hérités. Par ailleurs, les comptes utilisant des plans par dépôt hérités ne peuvent pas accéder aux registres qui prennent en charge les autorisations granulaires, car ces comptes sont facturés par dépôt. Pour obtenir la liste des registres prenant en charge les autorisations granulaires, consultez la section « À propos des autorisations pour les packages GitHub ». Pour plus d’informations, consultez « Plans de GitHub ».

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

GitHub Packages prend uniquement en charge l’authentification à l’aide d’un personal access token (classic). Pour plus d’informations, consultez « Gestion de vos jetons d’accès personnels ».

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. 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 dans un workflow GitHub Actions

Ce registre prend en charge les autorisations granulaires. Pour les registres prenant en charge les autorisations granulaires, si votre workflow GitHub Actions utilise un personal access token pour s’authentifier auprès d’un registre, nous vous recommandons vivement de mettre à jour votre workflow pour utiliser GITHUB_TOKEN. Pour obtenir des conseils sur la mise à jour de vos workflows qui s’authentifient auprès d’un registre avec un personal access token, consultez « Publication et installation d’un package avec GitHub Actions ».

Remarque : la capacité des workflows GitHub Actions de supprimer et de restaurer des packages à l’aide de l’API REST est actuellement en version bêta publique et susceptible d’être modifiée.

Vous pouvez utiliser un GITHUB_TOKEN dans un workflow GitHub Actions pour supprimer ou restaurer un package via l’API REST si le jeton dispose de l’autorisation admin sur le package. Les référentiels qui publient des packages à l’aide d’un workflow et les référentiels que vous avez explicitement connectés à des packages se voient automatiquement accorder l’autorisation admin aux packages dans le référentiel.

Pour plus d’informations sur GITHUB_TOKEN, consultez « Authentification par jeton automatique ». Pour plus d’informations sur les bonnes pratiques lors de l’utilisation d’un registre dans des actions, consultez « Durcissement de la sécurité pour GitHub Actions ».

Vous pouvez également choisir d’accorder des autorisations d’accès aux packages indépendamment pour GitHub Codespaces et GitHub Actions. Pour plus d’informations, consultez « Configuration du contrôle d’accès et de la visibilité d’un package » et « Configuration du contrôle d’accès et de la visibilité d’un package ».

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 « Présentation de GitHub Packages ».

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@rubygems.pkg.github.com/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 auquel la gemme est délimitée.

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@rubygems.pkg.github.com/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 auquel la gemme est délimitée.

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

Publication d’un package

Lorsque vous publiez un package pour la première fois, la visibilité par défaut est privée. Pour modifier la visibilité ou définir les autorisations d’accès, consultez « Configuration du contrôle d’accès et de la visibilité d’un package ». Pour plus d’informations sur la création de votre gemme, consultez « Créer votre propre gemme » dans la documentation de RubyGems.

Remarque : Si vous publiez un package lié à un dépôt, le package hérite automatiquement des autorisations d’accès du dépôt lié, tandis que les workflows GitHub Actions du dépôt lié accèdent automatiquement au package, sauf si votre organisation a désactivé l’héritage automatique des autorisations d’accès. Pour plus d’informations, consultez « Configuration du contrôle d’accès et de la visibilité d’un package ».

  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 auquel le package sera délimité et GEM_NAME par le nom de votre package gem.

    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://rubygems.pkg.github.com/NAMESPACE \
GEM_NAME-0.0.1.gem

Connexion d’un package à un dépôt

Le registre RubyGems stocke les packages dans votre compte d’organisation ou personnel et vous autorise à associer les packages à un dépôt. Vous pouvez choisir d’hériter des autorisations d’un dépôt ou de définir des autorisations granulaires indépendamment d’un dépôt.

Vous pouvez vous assurer que les gemmes seront liées à un dépôt dès qu’elles seront publiées en incluant l’URL du dépôt GitHub dans le champ github_repo dans gem.metadata. Vous pouvez lier plusieurs gemmes au même dépôt.

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

Pour plus d’informations sur la liaison d’un package publié à un dépôt, consultez « Connexion d’un dépôt à un package ».

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 auquel la gemme que vous souhaitez installer est délimitée.

    source "https://rubygems.org"

gem "rails"

source "https://rubygems.pkg.github.com/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://rubygems.pkg.github.com/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