Nota: Actualmente los ejecutores hospedados en GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.
Introducción
Esta guía te muestra cómo crear un flujo de trabajo que publique paquetes Node.js en el GitHub Packages y registros npm después de que se aprueben las pruebas de integración continua (CI).
Prerrequisitos
Recomendamos que tengas un conocimiento básico de las opciones de configuración de flujo de trabajo y de cómo crear un archivo de flujo de trabajo. Para obtener más información, vea «Más información sobre las Acciones de GitHub».
Para obtener más información sobre la creación de un flujo de trabajo CI para tu proyecto Node.js, consulta "Crear y probar en Node.js."
También puede ser útil tener un entendimiento básico de lo siguiente:
- "Trabajar con el registro de npm"
- "variables"
- "Uso de secretos en Acciones de GitHub"
- "Autenticación automática de tokens"
Acerca de la configuración del paquete
Los campos name
y version
del archivo package.json
crean un identificador único que los registros usan para vincular el paquete a un registro. Puedes agregar un resumen para la página de lista de paquetes mediante la inclusión de un campo description
en el archivo package.json
. Para más información, vea "Creación de un archivo package.json" y "Creación de módulos de Node.js" en la documentación de npm.
Cuando existe un archivo .npmrc
local y tiene un valor registry
especificado, el comando npm publish
usa el registro configurado en el archivo .npmrc
. Puede usar la acción setup-node
para crear un archivo .npmrc local en el ejecutor que configure el registro y el ámbito predeterminados. La acción setup-node
también acepta un token de autenticación como entrada, que se usa para acceder a los registros privados o publicar paquetes de nodos. Para más información, vea setup-node
.
Puede especificar la versión de Node.js instalada en el ejecutor mediante la acción setup-node
.
Si agregas pasos en el flujo de trabajo para configurar los campos publishConfig
del archivo package.json
, no es necesario especificar la URL de registro mediante la acción setup-node
, pero estarás limitado a publicar el paquete en un solo registro. Para más información, vea "publishConfig" en la documentación de npm.
Publicar paquetes en el registro npm
Puedes desencadenar un flujo de trabajo para publicar tu paquete cada vez que publiques un lanzamiento nuevo. El proceso del ejemplo siguiente se ejecuta cuando se desencadena el evento de lanzamiento de tipo published
. Si se superan las pruebas de CI, el proceso carga el paquete en el registro npm. Para obtener más información, vea «Administrar lanzamientos en un repositorio».
Para realizar operaciones autenticadas frente al registro npm en tu flujo de trabajo, necesitarás almacenar tu token de autenticación npm como un secreto. Por ejemplo, cree un secreto de repositorio denominado NPM_TOKEN
. Para obtener más información, vea «Uso de secretos en Acciones de GitHub».
De manera predeterminada, npm usa el campo name
del archivo package.json
para determinar el nombre del paquete publicado. Al publicar en un espacio de nombres global, solo necesitas incluir el nombre del paquete. Por ejemplo, publicaría un paquete denominado my-package
en https://www.npmjs.com/package/my-package
.
Si vas a publicar un paquete que incluye un prefijo de ámbito, incluya el ámbito en el nombre del archivo package.json
. Por ejemplo, si el prefijo de ámbito de npm es "octocat" y el nombre del paquete es "hello-world", name
en el archivo package.json
debe ser @octocat/hello-world
. Si en el paquete npm se usa un prefijo de ámbito y el paquete es público, tendrá que usar la opción npm publish --access public
. Esta es una opción que npm requiere para evitar que alguien publique un paquete privado involuntariamente.
En este ejemplo se almacena el secreto NPM_TOKEN
en la variable de entorno NODE_AUTH_TOKEN
. Cuando la acción setup-node
crea un archivo .npmrc
, hace referencia al token de la variable de entorno NODE_AUTH_TOKEN
.
name: Publish Package to npmjs on: release: types: [published] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 # Setup .npmrc file to publish to npm - uses: actions/setup-node@v4 with: node-version: '16.x' registry-url: 'https://registry.npmjs.org' - run: npm ci - run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
name: Publish Package to npmjs
on:
release:
types: [published]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Setup .npmrc file to publish to npm
- uses: actions/setup-node@v4
with:
node-version: '16.x'
registry-url: 'https://registry.npmjs.org'
- run: npm ci
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
En el ejemplo anterior, la acción setup-node
crea un archivo .npmrc
en el ejecutor con el contenido siguiente:
//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
registry=https://registry.npmjs.org/
always-auth=true
Tenga en cuenta que debe establecer registry-url
en https://registry.npmjs.org/
en setup-node
para configurar correctamente las credenciales.
Sube paquetes al GitHub Packages
Puedes desencadenar un flujo de trabajo para publicar tu paquete cada vez que publiques un lanzamiento nuevo. El proceso del ejemplo siguiente se ejecuta cuando se desencadena el evento de lanzamiento de tipo published
. Si se superan las pruebas de CI, el proceso carga el paquete en el GitHub Packages. Para obtener más información, vea «Administrar lanzamientos en un repositorio».
Configurar el repositorio de destino
Vincular tu paquete a GitHub Packages con la clave repository
es opcional. Si decides no proporcionar la clave repository
en el archivo package.json
, GitHub Packages publica un paquete en el repositorio de GitHub que especifiques en el campo name
del archivo package.json
. Por ejemplo, un paquete denominado @my-org/test
se publica en el repositorio my-org/test
de GitHub. Si el url
especificado en la clave repository
no es válido, aún es posible que se publique el paquete, pero no estará vinculado al origen del repositorio, tal y como se pretendía.
Si proporcionas la clave repository
en tu archivo package.json
, el repositorio en esa clave se utilizará como el registro npm de destino para GitHub Packages. Por ejemplo, la publicación de los siguientes resultados de package.json
en un paquete denominado my-package
publicado en el repositorio GitHub octocat/my-other-repo
. Una vez publicado, solo se actualiza el origen del repositorio y el paquete no hereda ningún permiso del repositorio de destino.
{
"name": "@octocat/my-package",
"repository": {
"type": "git",
"url": "https://github.com/octocat/my-other-repo.git"
},
Autenticarse en el repositorio de destino
Para realizar operaciones autenticadas en el registro GitHub Packages en el flujo de trabajo, puede usar GITHUB_TOKEN
. El secreto GITHUB_TOKEN
se establece en un token de acceso para el repositorio cada vez que comienza un trabajo en un flujo de trabajo. Debes establecer los permisos para este token de acceso en el archivo del flujo de trabajo a fin de conceder acceso de lectura al ámbito contents
y acceso de escritura al ámbito packages
. Para obtener más información, vea «Autenticación automática de tokens».
Si quieres publicar tu paquete en un repositorio diferente, debes usar un personal access token que tenga permisos de escritura en los paquetes del repositorio destino. Para obtener más información, vea «Administración de tokens de acceso personal» y «Uso de secretos en Acciones de GitHub».
Flujo de trabajo de ejemplo
En este ejemplo se almacena el secreto GITHUB_TOKEN
en la variable de entorno NODE_AUTH_TOKEN
. Cuando la acción setup-node
crea un archivo .npmrc
, hace referencia al token de la variable de entorno NODE_AUTH_TOKEN
.
name: Publish package to GitHub Packages on: release: types: [published] jobs: build: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkout@v4 # Setup .npmrc file to publish to GitHub Packages - uses: actions/setup-node@v4 with: node-version: '16.x' registry-url: 'https://npm.pkg.github.com' # Defaults to the user or organization that owns the workflow file scope: '@octocat' - run: npm ci - run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
name: Publish package to GitHub Packages
on:
release:
types: [published]
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
# Setup .npmrc file to publish to GitHub Packages
- uses: actions/setup-node@v4
with:
node-version: '16.x'
registry-url: 'https://npm.pkg.github.com'
# Defaults to the user or organization that owns the workflow file
scope: '@octocat'
- run: npm ci
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
La acción setup-node
crea un archivo .npmrc
en el ejecutor. Cuando se usa la entrada scope
en la acción setup-node
, el archivo .npmrc
incluye el prefijo de ámbito. De manera predeterminada, la acción setup-node
establece el ámbito en el archivo .npmrc
en la cuenta que contiene ese archivo de flujo de trabajo.
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://npm.pkg.github.com
always-auth=true
Publicar paquetes mediante Yarn
Si usas el gestor de paquetes Yarn, puedes instalar y publicar paquetes mediante Yarn.
name: Publish Package to npmjs on: release: types: [published] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 # Setup .npmrc file to publish to npm - uses: actions/setup-node@v4 with: node-version: '16.x' registry-url: 'https://registry.npmjs.org' # Defaults to the user or organization that owns the workflow file scope: '@octocat' - run: yarn - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
name: Publish Package to npmjs
on:
release:
types: [published]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Setup .npmrc file to publish to npm
- uses: actions/setup-node@v4
with:
node-version: '16.x'
registry-url: 'https://registry.npmjs.org'
# Defaults to the user or organization that owns the workflow file
scope: '@octocat'
- run: yarn
- run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Para autenticarse con el registro durante la publicación, asegúrate de que el token de autenticación también esté definido en el archivo yarnrc.yml
. Para obtener más información, consulta el artículo Configuración en la documentación de Yarn.