Publicar e instalar un paquete con GitHub Actions

Puedes configurar un flujo de trabajo en GitHub Actions para publicar o instalar automáticamente un paquete desde Registro del paquete de GitHub.

el Registro del paquete de GitHub se encuentra disponible con GitHub Free, GitHub Pro, GitHub Free para organizaciones, GitHub Team, Nube de GitHub Enterprise, GitHub Enterprise Server, y GitHub AE.


Registro del paquete de GitHub 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 Registro de contenedores ya que estas cuentas se facturan por repositorio. Para obtener más información, consulta la sección "[Productos de GitHub](/articles/github-s-products)".

Acerca de Registro del paquete de GitHub con GitHub Actions

GitHub Actions te ayuda a automatizar tus flujos de trabajo de desarrollo de software en el mismo lugar en el que almacenas código y colaboras con informes de problemas y solicitudes de extracción. Puedes escribir tareas individuales, llamadas acciones, y combinarlas para crear un flujo de trabajo personalizado. Con GitHub Actions puedes crear capacidades de integración continua (CI, por sus siglas en inglés) de extremo a extremo y de funcionamiento continuo (CD, por sus siglas en inglés) directamente en tu repositorio. Para obtener más información, consulta "Acerca de GitHub Actions."

Puedes ampliar las capacidades de CI y CD de tu repositorio publicando o instalando paquetes como parte de tu flujo de trabajo.

Autenticarse en el Registro de contenedores

Para autenticarse en el Registro de contenedores dentro de un flujo de trabajo de GitHub Actions, utiliza el GITHUB_TOKEN para tener la mejor experiencia en seguridad. Si tu flujo de trabajo está utilizando un token de acceso personal (PAT) para autenticarse en ghcr.io, entonces te recomendamos ampliamente que actualices tu flujo de trabajo para utilizar el GITHUB_TOKEN.

Para obtener orientación sobre cómo actualizar tus flujos de trabajo que se autentican en ghcr.io con un token de acceso personal, consulta la sección "Mejorar un flujo de trabajo que acceda a ghcr.io".

Para obtener más información sobre el GITHUB_TOKEN, consulta la sección "Autenticación en un flujo de trabajo".

Si estás utilizando el Registro de contenedores en las acciones, sigue nuestras mejores prácticas de seguridad en "Fortalecimiento de seguridad para las Acciones de GitHub".

Autenticarse en los registros de paquetes en GitHub

Si quieres que tu flujo de trabajo se autentique en el Registro del paquete de GitHub para acceder a un registro de paquetes diferente al Registro de contenedores en GitHub, entonces te recomendamos utilizar el GITHUB_TOKEN que GitHub crea automáticamente para tu repositorio cuando habilitas las GitHub Actions en vez de un token de acceso personal para autenticación. Debes configurar los permisos para este token de acceso en el archivo del flujo de trabajo para otorgar acceso de lectura para el alcance contents y acceso de escritura para el de packages. Para las bifurcaciones, se otorga acceso de lectura al GITHUB_TOKEN en el repositorio padre. Para obtener más información, consulta "Autenticar con el GITHUB_TOKEN".

Puedes hacer referencia al GITHUB_TOKEN en tu archivo de flujo de trabajo mediante el contexto {{secrets.GITHUB_TOKEN}}. Para más información, consulta "Autenticando con el GITHUB_TOKEN."

Acerca de los permisos y acceso a los paquetes para los paquetes que pertenecen a los repositorios

Nota: Los paquetes que pertenecen a repositorios incluyen RubyGems, npm, Apache Maven, NuGet, y Gradle.

Cuando habilitas las Acciones de GitHub, GitHub instala una App GitHub en tu repositorio. El secreto del GITHUB_TOKEN es un token de acceso a la instalación de GitHub App. Puedes utilizar el token de acceso a la instalación para autenticarte en nombre de la GitHub App instalada en tu repositorio. Los permisos del token están limitados al repositorio que contiene tu flujo de trabajo. Para obtener más información, consulta la sección "Permisos para el GITHUB_TOKEN".

El Registro del paquete de GitHub te permite subir y extraer paquetes mediante el GITHUB_TOKEN que está disponible para un flujo de trabajo de GitHub Actions.

Acerca de los permisos y el acceso de paquetes para el Registro de contenedores

El Registro de contenedores (ghcr.io) permite a los usuarios crear y administrar contenedores como recursos independientes a nivel organizacional. Los contenedores pueden pertenecer a una organización o a una cuenta de usuario personal y puedes personalizar el acceso para cada uno de tus contenedores por aparte de los permisos del repositorio.

Todos los flujos de trabajo que accedan al Registro de contenedores deben utilizar el GITHUB_TOKEN en vez de un token de acceso personal. Para obtener más información acerca de las mejores prácticas de seguridad, consulta la sección "Fortalecimiento de seguridad para las GitHub Actions".

Configuración de acceso y permisos predeterminados para los contenedores que se modifican a través de los flujos de trabajo

Cuando creas, instalas, modificas o borras un contenedor a través de un flujo de trabajo, hay algunos permisos y configuraciones de acceso predeterminados que se utilizan para garantizar que los administradores tengan acceso al fluljo de trabajo. También puedes ajustar esta configuración de acceso.

Por ejemplo, predeterminadamente, si un flujo de trabajo crea un contenedor que utilice el GITHUB_TOKEN, entonces:

  • El contenedor hereda la visibilidad el modelo de permisos del repositorio en donde se ejecuta el flujo de trabajo.
  • Los administradores de repositorio donde se ejecuta el flujo de trabajo se convierten en los administradores del contenedor una vez que este se cree.

Estos son más ejemplos de cómo funcionan los permisos predeterminados para los flujos de trabajo que administran paquetes.

Tarea de flujo de trabajo de GitHub ActionsAcceso y permisos predeterminados
Descargar un contenedor existente- Si el contenedor es público, cualquier flujo de trabajo que se ejecute en cualquier repositorio puede descargar el contenedor.
- Si el contenedor es interno, entonces todos los flujos de trabajo que se ejecuten en un repositorio que pertenezca a la cuenta empresarial podrá descargarlo. Para las organziaciones que pertenecen a una empresa, puedes leer cualquier repositorio en la empresa
- Si el contenedor es privado, solo los flujos de trabajo que se ejecuten en los repositorios a los que se les otorga permiso de lectura en dicho contenedor podrán descargarlo.
Carga una versión nueva a un contenedor existente- Si el contenedor es privado, interno, o público, solo los flujos de trabajo que se ejecuten en repositorios que tengan el permiso de escritura en dicho contenedor podrán cargar versiones nuevas de este.
Borrar un contenedor o versiones de un contenedor- Si el contenedor es privado, interno o público, solo los flujos de trabajo que se ejecuten en los repositorios a los que se les otorga permiso de borrado podrán borrar las versiones existentes de este.

También puedes ajustar el acceso a los contenedores de forma más granular o ajustar el comportamiento de algunos de los permisos predeterminados. Para obtener más información, consulta la sección "Configurar la visibilidad y el control de accesos de un paquete".

Publicar un paquete mediante una acción

Puedes utilizar GitHub Actions para publicar paquetes automáticamente como parte de tu flujo de integración contínua (IC). Este acercamiento a los despliegues contínuos (DC) te permite automatizar la creación de nuevas versiones de los paquetes si el código cumple con tus estándares de calidad. Por ejemplo, podrías crear un flujo de trabajo que ejecute pruebas de IC cada vez que un desarrollador suba código a alguna rama en particular. Si estas pruyebas pasan, el flujo de trabajo puede publicar una versión nueva del paquete en el Registro del paquete de GitHub.

Los pasos de configuración varían de acuerdo con el cliente del paquete. Para obtener información general sobre como configurar un flujo de trabajo para GitHub Actions, consulta la sección "Configurar un flujo de trabajo".

El siguiente ejemplo ilustra cómo puedes utilizar las GitHub Actions para crear tu app y luego crear una imagen de Docker automáticamente y publicarla en el Registro del paquete de GitHub.

Crea un archivo de flujo de trabajo nuevo en tu repositorio (tal como .github/workflows/deploy-image.yml), y agrega el siguiente YAML:

YAML
# This workflow uses actions that are not certified by GitHub.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# documentación.

name: Create and publish a Docker image

on:
  push:
    branches: ['release']

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Log in to the Container registry
        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Build and push Docker image
        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

La configuración relevante se explica en la siguiente tabla. Para encontrar los detalles completos de cada elemento en un flujo de trabajo, consulta la sección "Sintaxis de flujo de trabajo para GitHub Actions".

on:
  push:
    branches: ['release']
Configura el flujo de trabajo de Crear y publicar una imagen de Docker para que se ejecute cada vez que se sube un cambio a la rama que se llama release.
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
Define dos variables de ambiente personalizadas para el flujo de trabajo. Estas se utilizan para el dominio del Registro de contenedores y para un nombre para la imagen de Docker que compila este flujo de trabajo.
jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
Hay solo un job en este flujo de trabajo. Se configura para ejecutarse en la última versión disponible de Ubuntu.
permissions: 
  contents: read
  packages: write 
Configura los permisos que se otorgan al GITHUB_TOKEN para las acciones en este job.
- name: Log in to the Container registry
  uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
  with:
    registry: ${{ env.REGISTRY }}
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
Crea un paso que se llama Log in to the Registro de contenedores, el cual se asienta en el registro utilizando la cuenta y contraseñas que publicarán los paquetes. Una vez que se publica, los paquetes pertenecerán a la cuenta que se define aquí.
- name: Extract metadata (tags, labels) for Docker
  id: meta
  uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
  with:
    images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
Este paso utiliza docker/metadata-action para extrar etiquetas y marcas que se aplicarán a la imagen específica. La id "meta" permite que se referencie la salida de este paso en otro subsecuente. El valor images proporciona el nombre base para las etiquetas y marcadores.
- name: Build and push Docker image
Crea un paso nuevo que se llama Build and push Docker image. Este paso se ejecuta como parte del job build-and-push-image.
uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
Utiliza la acción build-push-action de Docker para crear la imagen, basándose en el Dockerfile de tu repositorio. Si la compilación es exitosa, sube la imagen al Registro del paquete de GitHub.
with:
Envía los parámetros requeridas a la acción build-push-action. Estas se definen en líneas subsecuentes.
context: .
Define el contexto de la compilación como el conjunto de archivos que se ubican en la ruta específica. Para obtener más información, consulta la sección "Uso".
push: true
Sube esta imagen al registro si se compila con éxito.
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
Agrega las etiquetas y marcadores que se exrayeron en el paso "meta".

Este flujo de trabajo nuevo se ejecutará automáticamente cada que subas un cambio a una rama que se llame release en el repositorio. Puedes ver el progreso en la pestaña de Acciones.

Unos minutos después de que se complete el flujo de trabajo, el paquete nuevo podrá visualizarse en tu repositorio. Para encontrar tus paquetes disponibles, consulta la sección "Visualizar los paquetes de un repositorio".

Instalar un paquete mediante una acción

Puedes instalar paquetes como parte de tu flujo de CI mediante GitHub Actions. Por ejemplo, podrías configurar un flujo de trabajo para que cada vez que un programador suba código a una solicitud de extracción, el flujo de trabajo resuelva las dependencias al descargar e instalar paquetes alojados por el Registro del paquete de GitHub. Luego, el flujo de trabajo puede ejecutar pruebas de CI que requieran las dependencias.

El instalar los paquetes que hospeda el Registro del paquete de GitHub a través de las GitHub Actions requiere una configuración mínima o autenticación adicional cuando utilizas un GITHUB_TOKEN. También, la transferencia de datos es gratuita cuando una acción instala un paquete. Para obtener más información, consulta la sección "Acerca de la facturación para el Registro del paquete de GitHub".

Los pasos de configuración varían de acuerdo con el cliente del paquete. Para obtener información general sobre como configurar un flujo de trabajo para GitHub Actions, consulta la sección "Configurar un flujo de trabajo".

Actualizar un flujo de trabajo que tiene acceso a ghcr.io

El Registro de contenedores es compatible con el GITHUB_TOKEN para una autenticación más fácil y segura en tus flujos de trabajo. Si tu flujo de trabajo está utilizando un token de acceso personal (PAT) para autenticarse en ghcr.io, entonces te recomendamos ampliamente que actualices tu flujo de trabajo para utilizar el GITHUB_TOKEN.

Para obtener más información sobre el GITHUB_TOKEN, consulta la sección "Autenticación en un flujo de trabajo".

El utilizar el GITHUB_TOKEN en vez de un PAT, el cual incluya el alcance de repo, incrementa la seguridad de tu repositorio, ya que no necesita sutilizar un PAT de vida extendida que ofrezca acceso innecesario al repositorio en donde se ejecuta tu flujo de trabajo. Para obtener más información acerca de las mejores prácticas de seguridad, consulta la sección "Fortalecimiento de seguridad para las GitHub Actions".

  1. Navega a la página de llegada de tu paquete.

  2. En la barra lateral izquierda, haz clic en Acceso a las acciones. Opción "Acceso a las acciones" en el menú izquierdo

  3. Para asegurarte de que tu paquete de contenedor tenga acceso a tu flujo de trabajo, debes agregar el repositorio en donde se almacena el flujo de trabajo a tu contenedor. Haz clic en Agregar repositorio y busca el repositorio que quieres agregar. Botón "Agregar repositorio"

    Nota: Agregar un repositorio a tu contenedor a través de la opción de menú Acceso de las acciones es diferente que conectar tu contenedor a un repositorio. Para obtener más información, consulta las opciones "Garantizar a tu paquete acceso al flujo de trabajo" y "Conectar un repositorio a un paquete".

  4. Opcionalmente, utiliza el menú desplegable de "rol", selecciona el nivel de acceso predeterminado que te gustaría que tuviera el repositorio en tu imagen de contenedor. Niveles de acceso de permisos para otorgar a los repositorios

  5. Abre tu archivo de flujo de trabajo. En la línea en donde ingresas a ghcr.io, reemplaza tu PAT con ${{ secrets.GITHUB_TOKEN }}.

Por ejemplo, este flujo de trabajo publica una imagen de Docker utilizando ${{ secrets.GITHUB_TOKEN }} para autenticarse.

YAML
name: Demo Push

on:   
  push:
    # Publish `master` as Docker `latest` image.
    branches:
      - master
      - seed

    # Publish `v1.2.3` tags as releases.
    tags:
      - v*

  # Run tests for any PRs.
  pull_request:

env:
  IMAGE_NAME: ghtoken_product_demo

jobs:
  # Push image to GitHub Packages.
  # See also https://docs.docker.com/docker-hub/builds/
  push:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read

    steps:
      - uses: actions/checkout@v2

      - name: Build image
        run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}"

      - name: Log in to registry
        # This is where you will update the PAT to GITHUB_TOKEN
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin

      - name: Push image
        run: |
          IMAGE_ID=ghcr.io/${{ github.repository_owner }}/$IMAGE_NAME

          # Change all uppercase to lowercase
          IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
          # Strip git ref prefix from version
          VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
          # Strip "v" prefix from tag name
          [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
          # Use Docker `latest` tag convention
          [ "$VERSION" == "master" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION
          docker tag $IMAGE_NAME $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION

¿Te ayudó este documento?

Política de privacidad

¡Ayúdanos a hacer geniales estos documentos!

Todos los documentos de GitHub son de código abierto. ¿Notas algo que esté mal o que no sea claro? Emite una solicitud de cambios.

Haz una contribución

O, aprende cómo contribuir.