Crear 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, consulta 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 el ambiente virtual.

Los ejecutores auto-hospedados tienen instalado Node.js para ejecutar las acciones de JavaScript. Para obtener más información acerca de los requisitos de los ejecutores auto-hospedados, consulta la sección "Acerca de los ejecutores auto-hospedados".

Prerrequisitos

Antes de comenzar, necesitarás descargar Node.js y crear un repositorio GitHub.

1. Descarga e instala Node.js 12.x, que incluye npm.

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

2. Crea un repositorio nuevo en GitHub. Puedes elegir cualquier nombre de repositorio o usar "hello-world-javascript-action" como este ejemplo. Puedes agregar estos archivos después de que tu proyecto se haya subido a GitHub. Para obtener más información, consulta "Crear un repositorio nuevo".

3. Clona tu repositorio en tu computadora. Para obtener más información, consulta "Clonar un repositorio".

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

   cd hello-world-javascript-action

5. Desde tu terminal, inicializa el directorio con un archivo package.json.

   npm init -y

Crear un archivo de metadatos de una acción

Crea un nuevo archivo action.yml en el directorio hello-world-javascript-action con el siguiente código de ejemplo. Para obtener más información, consulta la sección "Sintaxis de metadatos para GitHub Actions".

action.yml

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

Añadir paquetes de kit de herramientas de 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 del kit de herramientas @actions/Core brinda una interfaz a los comandos del flujo de trabajo, variables de entrada y salida, estados de salida y mensajes de depuración.

El kit de herramientas también ofrece un paquete @actions/github que devuelve un cliente autenticado Octokit REST y acceso a los contextos de acciones de GitHub.

El kit de herramientas ofrece más que los paquetes core y github. Para obtener más información, consulta el repositorio actions/toolkit.

En tu terminal, instala los paquetes core y github del kit de herramientas de acciones.

npm install @actions/core
npm install @actions/github

Ahora deberías ver un directorio node_modules con los módulos que acabas 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 [who-to-greet]" 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, puedes usar el paquete github. La acción que escribirás imprimirá el evento de webhook que carga el registro.

Agrega un archivo nuevo denominado index.js, con el siguiente código.

index.js

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 lanza un error en el ejemplo anterior index.js, core.setFailed(error.message); usa el paquete del kit de herramientas de acciones @actions/core para registrar un mensaje y establecer un código de salida defectuoso. Para obtener más información, consulta la sección "Configurar los códigos de salida para las 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 tu directorio hello-world-javascript-action, crea un archivo README.md que especifique la siguiente información:

• Una descripción detallada de lo que hace la acción.
• Argumentos necesarios de entrada y salida.
• Argumentos opcionales de entrada y salida.
• Secretos que utiliza la acción.
• Variables de entorno que utiliza la acción.
• Un ejemplo de cómo usar tu acción en un flujo de trabajo.

README.md

# Hello world docker action

Esta acción imprime "Hello World" o "Hello" + el nombre de una persona a quien saludar en el registro.

## Entradas

### `who-to-greet`

**Obligatorio** El nombre de la persona a quién saludar. Predeterminado `"World"`.

## Outputs

### `time`

El tiempo en que lo saludamos.

## Ejemplo de uso

uses: actions/hello-world-javascript-action@v1
with:
  who-to-greet: 'Mona the Octocat'

Confirmar, etiquetar y subir 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 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. Necesitarás verificar los paquetes core y github del kit de herramientas para el repositorio de tu acción.

Desde tu terminal, confirma tus archivos action.yml, index.js, node_modules, package.json, package-lock.json y README.md. Si agregaste un archivo .gitignore que enumera node_modules, deberás eliminar 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 obtener más información sobre el control de versiones de tu acción, consulta la sección "Acerca de las acciones".

git add action.yml index.js node_modules/* package.json package-lock.json README.md
git commit -m "Mi primera acción está lista"
git tag -a -m "Mi primera versión de acción" v1
git push --follow-tags

Como una alternativa para verificar tu directorio node_modules, puedes usar una herramienta denominada zeit/ncc para compilar tu código y los módulos en un archivo utilizado para la distribución.

1. Instala zeit/ncc al ajecutar este comando en tu terminal. npm i -g @zeit/ncc

2. Compila tu archivo index.js. ncc build index.js

   Verás un nuevo archivo dist/index.js con tu código y los módulos compilados.

3. Cambia la palabra clave main en tu archivo action.yml para usar el nuevo archivo dist/index.js. main: 'dist/index.js'

4. Si ya has comprobado tu directorio node_modules, eliminínalo. rm -rf node_modules/*

5. Desde tu terminal, confirma las actualizaciones para tu action.yml, dist/index.js y node_modules.

   git add action.yml dist/index.js node_modules/*
   git commit -m "Utiliza zeit/ncc"
   git tag -a -m "Mi primera versión de acción" v1
   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. Cuando una acción está en un repositorio privado, la acción solo puede usarse en flujos de trabajo en el mismo repositorio. Las acciones públicas pueden ser usadas por flujos de trabajo en cualquier repositorio.

Ejemplo usando una acción pública

El siguiente código de flujo de trabajo usa la acción hello world completada en el repositorio actions/hello-world-javascript-action. Copia el código de flujo de trabajo en un archivo .github/workflows/main.yml, pero reemplaza el repositorio actions/hello-world-javascript-action con el repositorio que creaste. También puedes reemplazar la entrada who-to-greet con tu nombre.

.github/workflows/main.yml

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: actions/hello-world-docker-action@v1
      with:
        who-to-greet: 'Mona the Octocat'
    # Usa los resultados del paso `hello`
    - name: Get the output time
      run: echo "The time was ${{ steps.hello.outputs.time }}"

Ejemplo usando una acción privada

Copia el siguiente ejemplo de código de flujo de trabajo en un archivo .github/workflows/main.yml en tu repositorio de acción. También puedes reemplazar la entrada who-to-greet con tu 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@v2
      - 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 }}"

Desde tu repositorio, da clic en la pestaña de Acciones y selecciona la última ejecución de flujo de trabajo. Deberías ver "Hello Mona the Octocat" o el nombre que usaste para la entrada who-to-greet y el registro horario impreso en el registro.