Skip to main content

Trabajar con el registro de RubyGems

Puedes configurar RubyGems para publicar un paquete para GitHub Packages y utilizar paquetes almacenados en GitHub Packages como dependencias en un proyecto Ruby con Bundler.

GitHub Packages está disponible con GitHub Free, GitHub Pro, GitHub Free para organizaciones, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 o superior y GitHub AE.
GitHub Packages no está disponible para repositorios privados que pertenezcan a cuentas que utilicen planes tradicionales por repositorio. Las cuentas que utilicen los planes tradicionales por repositorio tampoco podrán acceder al Container registry ya que estas cuentas se facturan por repositorio. Para más información, vea "Productos de GitHub".

Prerrequisitos

  • Debes contar con RubyGems 2.4.1 o superior. Para encontrar tu versión de RubyGems:

    $ gem --version
  • Debes tener Bundler 1.6.4 o superiores. Para encontrar tu versión Bundler:

    $ bundle --version
    Bundler version 1.13.7

Autenticar a GitHub Packages

GitHub Packages solo admite la autenticación mediante un personal access token (classic). Para obtener más información, consulta "Creación de un personal access token".

Necesitas un token de acceso para publicar, instalar y eliminar paquetes privados, internos y públicos.

Puedes usar un personal access token (classic) para autenticarte en GitHub Packages o en la API de GitHub. Cuando creas un personal access token (classic), puedes asignar al token diferentes ámbitos en función de tus necesidades. Para obtener más información sobre los ámbitos relacionados con paquetes para unpersonal access token (classic), consulta "Acerca de los permisos para los Paquetes de GitHub".

Para autenticarte en un registro del GitHub Packages dentro de un flujo de trabajo de GitHub Actions, puedes utilizar:

  • GITHUB_TOKEN para publicar los paquetes asociados con el repositorio del flujo de trabajo.
  • Un personal access token (classic) con, al menos, ámbito de packages:read para instalar los paquetes asociados con otros repositorios privados (a los cuales no puede acceder GITHUB_TOKEN).

Autenticación en un flujo de trabajo de GitHub Actions

Este registro admite permisos granulares. Para los registros que admiten permisos detallados, si en el flujo de trabajo se usa un personal access token para autenticarse en un registro, se recomienda encarecidamente actualizar el flujo de trabajo para usar el GITHUB_TOKEN. Para obtener instrucciones sobre cómo actualizar los flujos de trabajo que se autentican en un registro con un personal access token, consulta "Actualización de un flujo de trabajo que accede a un registro mediante un personal access token".

Para más información sobre GITHUB_TOKEN, vea "Autenticación en un flujo de trabajo". Para obtener más información sobre los procedimientos recomendados al usar un registro en acciones, consulta "Fortalecimiento de seguridad para Acciones de GitHub".

También puedes optar por conceder permisos de acceso a paquetes de forma independiente para GitHub Codespaces y GitHub Actions. Para obtener más información, consulta "Garantizar el acceso de Codespaces al paquete" y "Garantizar el acceso al flujo de trabajo para tu paquete".

Autenticación con un personal access token

Debes utilizar un personal access token (classic) con los ámbitos adecuados para publicar e instalar paquetes en GitHub Packages. Para más información, vea "Acerca de GitHub Packages".

Si quieres publicar e instalar gems, puedes configurar RubyGems o Bundler para autenticarse en GitHub Packages con tu personal access token.

Para publicar gems nuevos, debes autenticarte en GitHub Packages con RubyGems editando el archivo ~/.gem/credentials para incluir tu personal access token (classic). Cree un nuevo archivo ~/.gem/credentials si este archivo no existe.

Por ejemplo, puedes crear o editar un archivo ~/.gem/credentials para incluir lo siguiente, reemplazando TOKEN por tu personal access token.

---
:github: Bearer TOKEN

Para instalar gems, debes autenticarte en GitHub Packages actualizando tus orígenes de gems para incluir https://USERNAME:TOKEN@rubygems.pkg.github.com/OWNER/. Debes reemplazar:

  • USERNAME por su nombre de usuario de GitHub.
  • TOKEN por tu personal access token (classic).
  • OWNER por el nombre de la cuenta de usuario o de organización a la que pertenece el repositorio que contiene el proyecto.

Si quieres que el paquete esté disponible globalmente, puedes ejecutar el siguiente comando para agregar el registro como origen.

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

Para la autenticación con Bundler, configúralo para que use tu personal access token (classic), reemplazando USERNAME por tu nombre de usuario de GitHub, TOKEN por tu personal access token y OWNER por el nombre de la cuenta de usuario u organización que sea propietaria del repositorio que contiene el proyecto.

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

Publicación de un paquete

Cuando publicas un paquete por primera vez, la visibilidad predeterminada es privada. Cuando se vincula un paquete a un repositorio, la visibilidad del paquete depende de la visibilidad del repositorio. Para cambiar la visibilidad o establecer permisos de acceso, consulte "Configurar la visibilidad y el control de accesos de un paquete". Para más información sobre cómo crear la gema, consulta "Creación de una gema propia" en la documentación de RubyGems.

  1. Autentícate en GitHub Packages. Para obtener más información, vea "Autenticación en GitHub Packages".

  2. Compile el paquete a partir de gemspec para crear el paquete .gem.

    gem build <GEM NAME>.gemspec
    
  3. Publique un paquete en GitHub Packages, y reemplace OWNER por el nombre de la cuenta de usuario o de la organización y <GEM NAME> por el nombre del paquete de gemas.

    $ gem push --key github \
    --host https://rubygems.pkg.github.com/OWNER \
    <GEM NAME>-0.0.1.gem
    

Conexión de un paquete a un repositorio

En el registro de RubyGems se almacenan paquetes de la cuenta personal o de la organización, y permite asociar los paquetes a un repositorio. Puedes elegir si quieres heredar permisos desde un repositorio o si quieres configurar permisos granulares independientemente de un repositorio.

Puedes asegurarte de que las gemas se vincularán a un repositorio tan pronto como se publiquen si incluyes la dirección URL del repositorio GitHub en el campo github_repo de gem.metadata. Puedes vincular varias gemas al mismo repositorio.

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

Para obtener información sobre cómo vincular un paquete publicado con un repositorio, consulta "Conexión de un repositorio a un paquete".

Instalación de un paquete

Puede usar gemas de GitHub Packages de forma muy similar a las gemas de rubygems.org. Debe autenticarse en GitHub Packages agregando su usuario u organización de GitHub como origen en el archivo ~/.gemrc o mediante Bundler, editando el archivo Gemfile.

  1. Autentícate en GitHub Packages. Para obtener más información, vea "Autenticación en GitHub Packages".

  2. Para Bundler, agregue su usuario u organización de GitHub como origen en el archivo Gemfile para extraer gemas de este nuevo origen. Por ejemplo, puedes agregar un nuevo bloque source al archivo Gemfile que use GitHub Packages solo para los paquetes que especifiques, y reemplazar GEM NAME por el paquete que quieras instalar desde GitHub Packages y OWNER por el usuario u organización que posee la gema que quieres instalar.

    source "https://rubygems.org"
    
    gem "rails"
    
    source "https://rubygems.pkg.github.com/OWNER" do
      gem "GEM NAME"
    end
    
  3. En el caso de las versiones de Bundler anteriores a la 1.7.0, debe agregar un nuevo source global. Para obtener más información sobre el uso de Bundler, consulte la documentación de bundler.io.

    source "https://rubygems.pkg.github.com/OWNER"
    source "https://rubygems.org"
    
    gem "rails"
    gem "GEM NAME"
    
  4. Instala el paquete:

    $ gem install <GEM NAME> --version "0.1.1"
    

Información adicional