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. Descarga e instala Node.js 20.x, que incluye npm.

   http://nodejs.org/en/download/

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

3. Clona tu repositorio en tu computadora. Para más información, consulta 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 más información, consulta 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: dist/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: dist/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 @actions/github

npm install @actions/core @actions/github

Ahora deberías ver un directorio node_modules y un archivo package-lock.json que realiza un seguimiento de las dependencias instaladas y sus versiones. No debes confirmar el directorio node_modules en el repositorio.

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 src/index.js con el código siguiente.

import * as core from "@actions/core";
import * as github from "@actions/github";

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput("who-to-greet");
  core.info(`Hello ${nameToGreet}!`);

  // Get the current time and set it as an output variable
  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);
  core.info(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

import * as core from "@actions/core";
import * as github from "@actions/github";

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput("who-to-greet");
  core.info(`Hello ${nameToGreet}!`);

  // Get the current time and set it as an output variable
  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);
  core.info(`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 más información, consulta 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
```

Confirmación, etiquetado e inserción de una acción

GitHub descarga cada acción ejecutada en un flujo de trabajo en tiempo de ejecución y la ejecuta como un paquete completo de código antes de que puedas 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. Por ejemplo, esta acción usa paquetes @actions/core y @actions/github.

La inserción del directorio node_modules en el repositorio puede causar problemas. Como alternativa, puedes usar herramientas como rollup.js o @vercel/ncc para combinar el código y las dependencias en un archivo para su distribución.

1. Instala rollup y sus complementos ejecutando este comando en el terminal.

   npm install --save-dev rollup @rollup/plugin-commonjs @rollup/plugin-node-resolve

2. Crea un nuevo archivo llamado rollup.config.js en la raíz del repositorio con el código siguiente.

   JavaScript

   import commonjs from "@rollup/plugin-commonjs";
   import { nodeResolve } from "@rollup/plugin-node-resolve";
   
   const config = {
     input: "src/index.js",
     output: {
       esModule: true,
       file: "dist/index.js",
       format: "es",
       sourcemap: true,
     },
     plugins: [commonjs(), nodeResolve({ preferBuiltins: true })],
   };
   
   export default config;
   

3. Compile el archivo dist/index.js.

   rollup --config rollup.config.js

   Verás un nuevo archivo dist/index.js con el código y las dependencias.

4. Desde el terminal, confirma las actualizaciones.

   Shell

   git add src/index.js dist/index.js rollup.config.js package.json package-lock.json README.md action.yml
   git commit -m "Initial commit of my first action"
   git tag -a -m "My first action release" v1.1
   git push --follow-tags
   

Al confirmar e insertar el código, el repositorio actualizado debe tener este aspecto:

hello-world-javascript-action/
├── action.yml
├── dist/
│   └── index.js
├── package.json
├── package-lock.json
├── README.md
├── rollup.config.js
└── src/
    └── index.js

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 más información, consulta 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:
    branches:
      - main

jobs:
  hello_world_job:
    name: A job to say hello
    runs-on: ubuntu-latest

    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:
    branches:
      - main

jobs:
  hello_world_job:
    name: A job to say hello
    runs-on: ubuntu-latest

    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.

on:
  push:
    branches:
      - main

jobs:
  hello_world_job:
    name: A job to say hello
    runs-on: ubuntu-latest

    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:
    branches:
      - main

jobs:
  hello_world_job:
    name: A job to say hello
    runs-on: ubuntu-latest

    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