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
En esta guía, aprenderás acerca de los componentes básicos necesarios para crear y usar una acción de JavaScript empaquetada. Para centrar esta guía en los componentes necesarios para empaquetar la acción, la funcionalidad del código de la acción es mínima. La acción imprime "Hello World" en los registros o "Hello [who-to-greet]"si proporcionas un nombre personalizado.
Esta guía usa el módulo Node.js del kit de herramientas GitHub Actions para acelerar el desarrollo. Para obtener más información, consulte el repositorio actions/toolkit.
Una vez que completes este proyecto, deberías comprender cómo crear tu propia acción de JavaScript y probarla en un flujo de trabajo.
Para garantizar que tus acciones de JavaScript son compatibles con todos los ejecutores hospedados en GitHub (Ubuntu, Windows, y macOS), el código empaquetado de JavaScript que escribas debe ser puramente JavaScript y no depender de otros binarios. Las acciones de JavaScript se ejecutan directamente en el ejecutor y utiliza binarios que ya existen en la imagen del ejecutor.
Advertencia: Cuando cree flujos de trabajo y acciones, siempre debe considerar si el código podría ejecutar entradas no confiables de atacantes potenciales. Se tratará a algunos contextos como una entrada no confiable, ya que un atacante podrían insertar su propio contenido malintencionado. Para obtener más información, vea «Fortalecimiento de seguridad para GitHub Actions».
Prerrequisitos
Antes de que comiences, necesitarás descargar Node.js y crear un repositorio público de GitHub.
-
Descargue e instale Node.js 16.x, que incluye npm.
-
Crea un repositorio público nuevo en tu instancia de GitHub Enterprise Server y llámalo "hello-world-javascript-action". Para obtener más información, vea «Crear un repositorio nuevo».
-
Clona tu repositorio en tu computadora. Para obtener más información, vea «Clonar un repositorio».
-
Desde tu terminal, cambia los directorios en tu repositorio nuevo.
Shell cd hello-world-javascript-action
cd hello-world-javascript-action
-
Desde el terminal, inicialice el directorio con npm para generar un archivo
package.json
.Shell npm init -y
npm init -y
Crear un archivo de metadatos de una acción
Cree un nuevo archivo denominado action.yml
en el directorio hello-world-javascript-action
con el siguiente código de ejemplo. Para obtener más información, vea «Sintaxis de metadatos para Acciones de GitHub».
name: 'Hello World' description: 'Greet someone and record the time' inputs: who-to-greet: # id of input description: 'Who to greet' required: true default: 'World' outputs: time: # id of output description: 'The time we greeted you' runs: using: 'node16' main: 'index.js'
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
who-to-greet: # id of input
description: 'Who to greet'
required: true
default: 'World'
outputs:
time: # id of output
description: 'The time we greeted you'
runs:
using: 'node16'
main: 'index.js'
Este archivo define la entrada who-to-greet
y la salida time
. También informa al ejecutor de la acción cómo empezar a ejecutar esta acción de JavaScript.
Agregar paquetes de kit de herramientas de las acciones
El kit de herramientas de acciones es una recopilación de los paquetes Node.js que te permiten desarrollar rápidamente acciones de JavaScript con más consistencia.
El paquete @actions/core
del kit de herramientas proporciona una interfaz para los comandos de flujo de trabajo, las variables de entrada y salida, los estados de salida y los mensajes de depuración.
El kit de herramientas también ofrece un paquete @actions/github
que devuelve un cliente autenticado de Octokit REST y acceso a los contextos de Acciones de GitHub.
El kit de herramientas ofrece mucho más que los paquetes core
y github
. Para obtener más información, consulte el repositorio actions/toolkit.
En el terminal, instale los paquetes core
y github
del kit de herramientas de acciones.
npm install @actions/core npm install @actions/github
npm install @actions/core
npm install @actions/github
Ahora debería ver un directorio node_modules
con los módulos que acaba de instalar y un archivo package-lock.json
con las dependencias del módulo instalado y las versiones de cada módulo instalado.
Escribir el código de la acción
Esta acción usa el kit de herramientas para obtener la variable de entrada who-to-greet
requerida en el archivo de metadatos de la acción e imprime "Hello [a_quien_se_salude]" en un mensaje de depuración del registro. A continuación, el script obtiene la hora actual y la establece como una variable de salida que pueden usar las acciones que se ejecutan posteriormente en un trabajo.
Las Acciones de GitHub proporcionan información de contexto sobre el evento de webhooks, las referencias de Git, el flujo de trabajo, la acción y la persona que activó el flujo de trabajo. Para acceder a la información de contexto, puede usar el paquete github
. La acción que escribirás imprimirá el evento de webhook que carga el registro.
Agregue un nuevo archivo denominado index.js
con el código siguiente.
const core = require('@actions/core'); const github = require('@actions/github'); try { // `who-to-greet` input defined in action metadata file const nameToGreet = core.getInput('who-to-greet'); console.log(`Hello ${nameToGreet}!`); const time = (new Date()).toTimeString(); core.setOutput("time", time); // Get the JSON webhook payload for the event that triggered the workflow const payload = JSON.stringify(github.context.payload, undefined, 2) console.log(`The event payload: ${payload}`); } catch (error) { core.setFailed(error.message); }
const core = require('@actions/core');
const github = require('@actions/github');
try {
// `who-to-greet` input defined in action metadata file
const nameToGreet = core.getInput('who-to-greet');
console.log(`Hello ${nameToGreet}!`);
const time = (new Date()).toTimeString();
core.setOutput("time", time);
// Get the JSON webhook payload for the event that triggered the workflow
const payload = JSON.stringify(github.context.payload, undefined, 2)
console.log(`The event payload: ${payload}`);
} catch (error) {
core.setFailed(error.message);
}
Si se produce un error en el ejemplo anterior index.js
, core.setFailed(error.message);
usa el paquete @actions/core
del kit de herramientas de acciones para registrar un mensaje y establecer un código de salida con errores. Para obtener más información, vea «Establecimiento de códigos de salida para acciones».
Crear un README
Puedes crear un archivo README para que las personas sepan cómo usar tu acción. Un archivo README resulta más útil cuando planificas el intercambio de tu acción públicamente, pero también es una gran manera de recordarle a tu equipo cómo usar la acción.
En el directorio hello-world-javascript-action
, cree un archivo README.md
que especifique la información siguiente:
- Una descripción detallada de lo que hace la acción.
- Los argumentos de entrada y salida obligatorios.
- Los argumentos de entrada y salida opcionales.
- Los secretos que usa la acción.
- Las variables de entorno que usa la acción.
- Un ejemplo de cómo usar la acción en un flujo de trabajo.
# Hello world javascript action This action prints "Hello World" or "Hello" + the name of a person to greet to the log. ## Inputs ### `who-to-greet` **Required** The name of the person to greet. Default `"World"`. ## Outputs ### `time` The time we greeted you. ## Example usage ```yaml uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b with: who-to-greet: 'Mona the Octocat' ```
# Hello world javascript action
This action prints "Hello World" or "Hello" + the name of a person to greet to the log.
## Inputs
### `who-to-greet`
**Required** The name of the person to greet. Default `"World"`.
## Outputs
### `time`
The time we greeted you.
## Example usage
```yaml
uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b
with:
who-to-greet: 'Mona the Octocat'
```
Confirma, etiqueta y sube tu acción a GitHub
GitHub Enterprise Server descarga cada acción ejecutada en un flujo de trabajo durante el tiempo de ejecución y la ejecuta como un paquete completo de código antes de que pueda usar comandos de flujo de trabajo como run
para interactuar con la máquina del ejecutor. Eso significa que debes incluir cualquier dependencia del paquete requerida para ejecutar el código de JavaScript. Tendrá que insertar los paquetes core
y github
del kit de herramientas en el repositorio de la acción.
Desde el terminal, confirme los archivos action.yml
, index.js
, node_modules
, package.json
, package-lock.json
y README.md
. Si agregó un archivo .gitignore
que enumera node_modules
, deberá quitar esa línea para confirmar el directorio node_modules
.
También es recomendable agregar una etiqueta de versión para los lanzamientos de tu acción. Para más información sobre el control de versiones de la acción, consulta "Acercad e las acciones personalizadas".
git add action.yml index.js node_modules/* package.json package-lock.json README.md git commit -m "My first action is ready" git tag -a -m "My first action release" v1.1 git push --follow-tags
git add action.yml index.js node_modules/* package.json package-lock.json README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1.1
git push --follow-tags
La inserción del directorio node_modules
en el repositorio puede causar problemas. Como alternativa, puede usar una herramienta que se denomina @vercel/ncc
para compilar el código y los módulos en un archivo usado para la distribución.
-
Instale
vercel/ncc
ejecutando este comando en el terminal.npm i -g @vercel/ncc
-
Compile el archivo
index.js
.ncc build index.js --license licenses.txt
Verá un nuevo archivo
dist/index.js
con el código y los módulos compilados. También verá un archivodist/licenses.txt
que lo acompaña y que contiene todas las licencias de los archivosnode_modules
que está usando. -
Cambie la palabra clave
main
del archivoaction.yml
para usar el nuevo archivodist/index.js
.main: 'dist/index.js'
-
Si ya ha insertado en el repositorio el directorio
node_modules
, quítelo.rm -rf node_modules/*
-
En el terminal, confirme las actualizaciones de los archivos
action.yml
,dist/index.js
ynode_modules
.Shell git add action.yml dist/index.js node_modules/* git commit -m "Use vercel/ncc" git tag -a -m "My first action release" v1.1 git push --follow-tags
git add action.yml dist/index.js node_modules/* git commit -m "Use vercel/ncc" git tag -a -m "My first action release" v1.1 git push --follow-tags
Probar tu acción en un flujo de trabajo
Ahora estás listo para probar tu acción en un flujo de trabajo.
Los flujos de trabajo de cualquier repositorio pueden usar acciones públicas. Cuando una acción está en un repositorio privado o interno, la configuración del repositorio indica si la acción está disponible solo en el mismo repositorio o también en los demás repositorios que pertenecen a la misma organización o empresa. Para obtener más información, vea «Administrar los ajustes de las GitHub Actions de un repositorio».
Nota: GitHub Actions en GitHub Enterprise Server pueden tener acceso limitado a las acciones de GitHub.com o GitHub Marketplace. Para más información, consulta "Administrar el acceso a las acciones desde GitHub.com" y ponte en contacto con el administrador del sitio de GitHub Enterprise.
Ejemplo usando una acción pública
Este ejemplo demuestra cómo se puede ejecutar tu acción nueva y pública desde dentro de un repositorio externo.
Copie el siguiente código YAML en un nuevo archivo en .github/workflows/main.yml
y actualice la línea uses: octocat/hello-world-javascript-action@v1.1
con su nombre de usuario y el nombre del repositorio público que ha creado anteriormente. También puede reemplazar la entrada who-to-greet
por su nombre.
on: [push] jobs: hello_world_job: runs-on: ubuntu-latest name: A job to say hello steps: - name: Hello world action step id: hello uses: octocat/hello-world-javascript-action@v1.1 with: who-to-greet: 'Mona the Octocat' # Use the output from the `hello` step - name: Get the output time run: echo "The time was ${{ steps.hello.outputs.time }}"
on: [push]
jobs:
hello_world_job:
runs-on: ubuntu-latest
name: A job to say hello
steps:
- name: Hello world action step
id: hello
uses: octocat/hello-world-javascript-action@v1.1
with:
who-to-greet: 'Mona the Octocat'
# Use the output from the `hello` step
- name: Get the output time
run: echo "The time was ${{ steps.hello.outputs.time }}"
Cuando se desencadene este flujo de trabajo, el ejecutor descargará la acción hello-world-javascript-action
desde su repositorio público y luego la ejecutará.
Ejemplo usando una acción privada
Copie el código de flujo de trabajo en un archivo .github/workflows/main.yml
del repositorio de la acción. También puede reemplazar la entrada who-to-greet
por su nombre.
.github/workflows/main.yml
on: [push] jobs: hello_world_job: runs-on: ubuntu-latest name: A job to say hello steps: # To use this repository's private action, # you must check out the repository - name: Checkout uses: actions/checkout@v4 - name: Hello world action step uses: ./ # Uses an action in the root directory id: hello with: who-to-greet: 'Mona the Octocat' # Use the output from the `hello` step - name: Get the output time run: echo "The time was ${{ steps.hello.outputs.time }}"
on: [push]
jobs:
hello_world_job:
runs-on: ubuntu-latest
name: A job to say hello
steps:
# To use this repository's private action,
# you must check out the repository
- name: Checkout
uses: actions/checkout@v4
- name: Hello world action step
uses: ./ # Uses an action in the root directory
id: hello
with:
who-to-greet: 'Mona the Octocat'
# Use the output from the `hello` step
- name: Get the output time
run: echo "The time was ${{ steps.hello.outputs.time }}"
En el repositorio, haga clic en la pestaña Actions y seleccione la última ejecución de flujo de trabajo. En Jobs o en el gráfico de visualización, haga clic en A job to say hello.
En el registro, debería ver el paso de acción Hola mundo y debería ver "Hello Mona the Octocat", o el nombre que haya usado para la entrada who-to-greet
impreso en el registro. Para ver la marca de tiempo, haz clic en Obtener la hora de salida.
Repositorios de plantillas para crear acciones de JavaScript
GitHub ofrece repositorios de plantillas para crear acciones de JavaScript y TypeScript. Puedes usar estas plantillas para empezar a crear rápidamente una nueva acción que incluya pruebas, linting y otros procedimientos recomendados.
Acciones de JavaScript de ejemplo en GitHub.com
Puedes encontrar muchos ejemplos de acciones de JavaScript en GitHub.com.