Creación de una acción de JavaScript

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.

Prerrequisitos

Antes de que comiences, necesitarás descargar Node.js y crear un repositorio público de GitHub.

1. Descargue e instale Node.js 20.x, que incluye npm.

   https://nodejs.org/en/download/

2. Crea un repositorio público nuevo en GitHub y llámalo "hello-world-javascript-action". Para obtener más información, vea «Crear un repositorio nuevo».

3. Clona tu repositorio en tu computadora. Para obtener más información, vea «Clonar un repositorio».

4. Desde tu terminal, cambia los directorios en tu repositorio nuevo.

   Shell

   cd hello-world-javascript-action
   

5. Desde el terminal, inicialice el directorio con npm para generar un archivo package.json.

   Shell

   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: 'node20'
  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: 'node20'
  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 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.

1. Instale vercel/ncc ejecutando este comando en el terminal.

   npm i -g @vercel/ncc

2. 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 archivo dist/licenses.txt que lo acompaña y que contiene todas las licencias de los archivos node_modules que está usando.

3. Cambie la palabra clave main del archivo action.yml para usar el nuevo archivo dist/index.js.

   main: 'dist/index.js'

4. Si ya ha insertado en el repositorio el directorio node_modules, quítelo.

   rm -rf node_modules/*

5. En el terminal, confirme las actualizaciones de los archivos action.yml, dist/index.js y node_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
   

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, 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 al mismo usuario o la misma organización. Para obtener más información, vea «Administrar los ajustes de las GitHub Actions de un repositorio».

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@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b 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@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
        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@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
        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.

• Repositorio de plantilla de javascript-action
• Repositorio de plantilla de typescript-action

Acciones de JavaScript de ejemplo en GitHub.com

Puedes encontrar muchos ejemplos de acciones de JavaScript en GitHub.com.

• DevExpress/testcafe-action
• duckduckgo/privacy-configuration