Trabajar con el registro de RubyGems

Nota: Cuando instalas o publicas una imagen de docker, Registro del paquete de GitHub no es compatible con capas externas, tales como imágenes de Windows.

Prerrequisitos

• Debes tener RubyGems 2.4.1 o superiores. 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

• Instala keycutter para administrar múltiples credenciales. Para instalar keycutter:

  $ gem install keycutter

Autenticarte en Registro del paquete de GitHub

Necesitas de un token de acceso para publicar, instalar, y borrar paquetes en Registro del paquete de GitHub.

Puees utilizar un token de acceso personal (PAT) para autenticarte en el Registro del paquete de GitHub o en la API de GitHub. Cuando creas un token de acceso personal, puedes asignar al token diferentes ámbitos en función de tus necesidades. Para obtener más información sobre los alcances relacionados con los paquetes para un PAT, consulta la sección "Acerca de los permisos para los Paquetes de GitHub".

Para autenticarte en un registro del Registro del paquete de GitHub 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 PAT para instalar los paquetes asociados con otros repositorios privados (a los cuales no puede acceder el GITHUB_TOKEN).

Para obtener más información sobre el GITHUB_TOKEN que se utiliza en los flujos de trabajo de GitHub Actions, consulta la sección "Autenticarse en un flujo de trabajo".

Autenticarte con un token de acceso personal

Debes utilizar un token de acceso personal con los alcances adecuados para publicar e instalar paquetes en Registro del paquete de GitHub. Para obtener más información, consulta "Acerca de Registro del paquete de GitHub".

Puedes autenticar a Registro del paquete de GitHub con RubyGems editando el archivo ~/.gem/credentials para publicar gemas, editar el archivo ~/.gemrc para instalar una gema única o usar Bundler para rastrear e instalar una o más gemas.

Para publicar gemas nuevas, debes autenticarte para Registro del paquete de GitHub con RubyGems editando tu archivo ~/.gem/credentials para incluir tu token de acceso personal. Crear un nuevo archivo ~/.gem/credentials si este archivo no existe.

Por ejemplo, crearías o editarías un ~/.gem/credentials para incluir lo siguiente, reemplazando TOKEN con tu token de acceso personal.

---
:github: Bearer TOKEN

Para instalar gemas, necesitas autenticarte en el Registro del paquete de GitHub mediante la edición del archivo ~/.gemrc para que tu proyecto incluya https://USERNAME:TOKEN@REGISTRY-URL/OWNER/. Debes reemplazar:

• USERNAME con tu nombre de usuario GitHub.
• TOKEN por tu token de acceso personal.
• OWNER con el nombre de la cuenta de usuario o de organización a la que pertenece el repositorio que contiene tu proyecto.
• REGISTRY-URL con la URL para el registro de Rubygems de tu instancia. Si tu instancia cuenta con el aislamiento de subdominios habilitado, utiliza rubygems.HOSTNAME. Si tu instancia cuenta con el aislamiento de subdominios inhabilitado, utiliza HOSTNAME/_registry/rubygems. Cualquiera que sea el caso, reemplaza HOSTNAME con el nombre de host de tu instancia de GitHub Enterprise Server.

Si no tienes un archivo ~/.gemrc, crea un nuevo archivo ~/.gemrc usando este ejemplo.

---
:backtrace: false
:bulk_threshold: 1000
:sources:
- https://rubygems.org/
- https://USERNAME:TOKEN@REGISTRY-URL/OWNER/
:update_sources: true
:verbose: true  

Para autenticar con Bundler, configura Bundler para que use tu token de acceso personal, reemplazando USERNAME con tu nombre de usuario de GitHub, TOKEN con tu token de acceso personal y OWNER con el nombre de la cuenta de usuario o de organización a la que pertenece el repositorio que contiene tu proyecto. Reemplaza REGISTRY-URL con la URL del registro de Rubygems de tu instancia. Si tu instancia cuenta con el aislamiento de subdominios habilitado, utiliza rubygems.HOSTNAME. Si tu instancia cuenta con el aislamiento de subdominios inhabilitado, utiliza HOSTNAME/_registry/rubygems. En cualquiera de los casos, reemplaza HOSTNAME con el nombre de host de tu instancia de GitHub Enterprise Server.

$ bundle config https://REGISTRY-URL/OWNER USERNAME:TOKEN

Publicar un paquete

Predeterminadamente, GitHub publica el paquete en un repositorio existente con el mismo nombre que éste. Por ejemplo, cuando publicas octo-gem a la organización octo-org, Registro del paquete de GitHub publica la gema en el repositorio octo-org/octo-gem. Para obtener más información sobre la creación de tu gema, consulta "Crear tu propia gema" en la documentación de RubyGems.

Después de que publiques un paquete, puedes verlo en GitHub. Para obtener más información, consulta "Visualizar paquetes".

1. Autentícate en Registro del paquete de GitHub. Para obtener más información, consulta "Autenticar a Registro del paquete de GitHub."

2. Construye el paquete desde el gemspec para crear el paquete .gem.

   gem build OCTO-GEM.gemspec

3. Publica un paquete en el Registro del paquete de GitHub, reemplazando OWNER con el nombre de la cuenta de usuario o de organización a la que pertenece el repositorio que contiene tu proyecto y OCTO-GEM con el nombre de tu paquete de gemas. Reemplaza REGISTRY-URL con la URL del registro de Rubygems de tu instancia. Si tu instancia cuenta con el aislamiento de subdominios habilitado, utiliza rubygems.HOSTNAME. Si tu instancia cuenta con el aislamiento de subdominios inhabilitado, utiliza HOSTNAME/_registry/rubygems. En cualquiera de los casos, reemplaza HOSTNAME con el nombre de host de tu instancia de GitHub Enterprise Server.

   $ gem push --key github \
   --host https://REGISTRY-URL/OWNER \
   OCTO-GEM-0.0.1.gem

Publicar varios paquetes en el mismo repositorio

Para publicar múltiples gemas en el mismo repositorio, puedes incluir la URL al repositorio GitHub en el campo github_repo en gem.metadata. Si incluyes este campo, GitHub empatará el repositorio con base en este valor en vez de utilizar el nombre de la gema. Reemplaza HOSTNAME con el nombre de host de tu instancia de GitHub Enterprise Server.

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

Instalar un paquete

Puedes usar gemas desde Registro del paquete de GitHub al igual que usas gemas de rubygems.org. Necesitas autenticarte en Registro del paquete de GitHub agregando tu usuario u organización GitHub como el orígen en el archivo ~/.gemrc o utilizando Bundler y editando tu Gemfile.

1. Autentícate en Registro del paquete de GitHub. Para obtener más información, consulta "Autenticar a Registro del paquete de GitHub."

2. Para Bundler, agrega tu usuario u organización GitHub como fuente en tu Gemfile para extraer gemas de esta nueva fuente. Por ejemplo, puedes agregar un bloque nuevo de source a tu Gemfile, el cual utilice el Registro del paquete de GitHub únicamente para los paquetes que especifiques, reemplazando a GEM NAME con el paquete que quieres instalar desde Registro del paquete de GitHub y a OWNER con el usuario u organización que es propietario del repositorio que contiene la gema que quieres instalar. Reemplaza la REGISTRY-URL con la URL para tu instancia del registro de Rubigems. Si tu instancia cuenta con el aislamiento de subdominios habilitado, utiliza rubygems.HOSTNAME. Si tu instancia cuenta con el aislamiento de subdominios inhabilitado, utiliza HOSTNAME/_registry/rubygems. En cualquiera de los casos, reemplaza HOSTNAME con el nombre de host de tu instancia de GitHub Enterprise Server.

   source "https://rubygems.org"
   
   gem "rails"
   
   source "https://REGISTRY-URL/OWNER" do
     gem "GEM NAME"
   end
   

3. Para las versiones de Bundler anteriores a 1.7.0, debes agregar una nueva fuente global. Para obtener más información acerca del uso de Bundler, consulta la documentación bundler.io.

   source "https://REGISTRY-URL/OWNER"
   source "https://rubygems.org"
   
   gem "rails"
   gem "GEM NAME"
   

4. Instala el paquete:

   $ gem install octo-gem --version "0.1.1"

Leer más

• "Borrar un paquete"