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 « Managing your personal access tokens ».
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 (auxquelsGITHUB_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. Quand un package est lié à un dépôt, sa visibilité dépend de celle du dépôt. 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 ».
-
Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez « Authentification auprès de GitHub Packages ».
-
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
-
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é etGEM_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.
-
Authentifiez-vous sur GitHub Packages. Pour plus d’informations, consultez « Authentification auprès de GitHub Packages ».
-
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çantGEM_NAME
par le package que vous souhaitez installer à partir de GitHub Packages etNAMESPACE
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
-
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"
-
Installez le package :
$ gem install GEM_NAME --version "0.1.1"