Creating a JavaScript action

Introduction

Dans ce guide, vous allez découvrir les composants de base qui sont nécessaires pour créer et utiliser une action JavaScript empaquetée. Afin de nous concentrer sur les composants nécessaires à l’empaquetage de l’action, nous avons réduit la fonctionnalité du code de l’action à son strict minimum. L’action affiche « Hello World » dans les journaux ou « Hello [who-to-greet] » si vous fournissez un nom personnalisé.

Ce guide utilise le module Node.js du kit de ressources GitHub Actions pour accélérer le développement. Pour plus d’informations, consultez le dépôt actions/toolkit.

Une fois que vous aurez terminé ce projet, vous saurez comment créer votre propre action JavaScript et la tester dans un workflow.

Pour garantir la compatibilité de vos actions JavaScript avec tous les exécuteurs hébergés sur GitHub (Ubuntu, Windows et macOS), le code JavaScript packagé que vous écrivez doit être du code JavaScript pur et ne doit pas dépendre d’autres fichiers binaires. Les actions JavaScript s’exécutent directement sur l’exécuteur et utilisent des fichiers binaires qui existent déjà dans l’image de l’exécuteur.

Prérequis

Avant de commencer, vous devez télécharger Node.js et créer un dépôt public GitHub.

1. Téléchargez et installez Node.js. 20.x, qui inclut npm.

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

2. Créez un dépôt public sur GitHub et appelez-le « hello-world-javascript-action ». Pour plus d’informations, consultez « Création d’un dépôt ».

3. Clonez votre dépôt sur votre ordinateur. Pour plus d’informations, consultez « Clonage d’un dépôt ».

4. À partir de votre terminal, remplacez les répertoires par votre nouveau dépôt.

   Shell

   cd hello-world-javascript-action
   

5. À partir de votre terminal, initialisez le répertoire avec npm pour générer un fichier package.json.

   Shell

   npm init -y
   

Création d’un fichier de métadonnées d’action

Créez un fichier nommé action.yml dans le répertoire hello-world-javascript-action avec l’exemple de code suivant. Pour plus d’informations, consultez « Référence syntaxique des métadonnées ».

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

Ce fichier définit l’entrée who-to-greet et la sortietime. Il indique également à l’exécuteur d’actions comment exécuter cette action JavaScript.

Ajout de packages de kit de ressources d’actions

Le kit de ressources d’actions est une collection de packages Node.js qui vous permet de créer rapidement des actions JavaScript avec plus de cohérence.

Le package @actions/core du kit de ressources fournit une interface aux commandes de workflow, aux variables d’entrée et de sortie, aux états de sortie et aux messages de débogage.

Le kit de ressources offre également un package @actions/github qui retourne un client REST Octokit authentifié et un accès aux contextes GitHub Actions.

Le kit de ressources offre plus que les packages core et github. Pour plus d’informations, consultez le dépôt actions/toolkit.

À partir de votre terminal, installez les packages core et github du kit de ressources d’actions.

npm install @actions/core @actions/github

npm install @actions/core @actions/github

Vous devriez maintenant voir un répertoire node_modules et un fichier package-lock.json qui suivent toutes les dépendances installées ainsi que leurs versions. Vous ne devez pas commiter le répertoire node_modules dans votre référentiel.

Écriture du code d’action

Cette action utilise le kit de ressources pour obtenir la variable d’entrée who-to-greet nécessaire dans le fichier de métadonnées de l’action, et affiche « Hello [who-to-greet] » dans un message de débogage dans le journal. Ensuite, le script obtient l’heure actuelle et la définit comme une variable de sortie que pourront utiliser les prochaines actions d’un travail.

GitHub Actions fournit des informations contextuelles sur l’événement webhook, les références Git, le workflow, l’action et la personne qui a déclenché le workflow. Pour accéder aux informations de contexte, vous pouvez utiliser le package github. L’action que vous allez écrire affiche la charge utile de l’événement webhook dans le journal.

Ajoutez un fichier nommé src/index.js en utilisant le code suivant.

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 une erreur est levée dans l’exemple index.js ci-dessus, core.setFailed(error.message); utilise le package @actions/core du kit de ressources d’actions pour journaliser un message et définir un code de sortie d’échec. Pour plus d’informations, consultez « Setting exit codes for actions ».

Création d’un fichier README

Pour expliquer aux utilisateurs comment utiliser votre action, vous pouvez créer un fichier README. Un fichier README est très utile si vous prévoyez de partager votre action publiquement, mais c’est aussi un excellent moyen de vous rappeler comment utiliser l’action.

Dans votre répertoire hello-world-javascript-action, créez un fichier README.md qui spécifie les informations suivantes :

• Une description détaillée de ce que fait l’action.
• Les arguments d’entrée et de sortie obligatoires.
• Les arguments d’entrée et de sortie facultatifs.
• Les secrets utilisés par l’action.
• Les variables d’environnement utilisées par l’action.
• Un exemple d’utilisation de votre action dans un workflow.

# 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
```

Engagez, marquez et poussez votre action

GitHub télécharge chaque action exécutée dans un flux de travail pendant la durée d'exécution et l'exécute comme un ensemble complet de code avant que vous puissiez utiliser des commandes de flux de travail comme run pour interagir avec la machine d'exécution. Cela signifie que vous devez inclure toutes les dépendances de package qui sont nécessaires pour exécuter le code JavaScript. Par exemple, cette action utilise les packages @actions/core et @actions/github.

Le check-in de votre répertoire node_modules peut entraîner des problèmes. Vous pouvez également utiliser des outils tels que rollup.js ou @vercel/ncc pour regrouper votre code et ses dépendances dans un seul fichier à distribuer.

1. Installez rollup et ses plugins en exécutant cette commande dans votre terminal.

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

2. Créez un nouveau fichier nommé rollup.config.js à la racine de votre référentiel avec le code suivant.

   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. Compilez votre fichier dist/index.js.

   rollup --config rollup.config.js

   Vous verrez un nouveau fichier dist/index.js contenant votre code et toutes les dépendances.

4. Depuis votre terminal, commiter les mises à jour.

   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
   

Lorsque vous commitez et envoyez (push) votre code, votre référentiel mis à jour devrait ressembler à ceci :

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

Tester votre action dans un workflow

Vous êtes maintenant prêt à tester votre action dans un workflow.

Les actions publiques peuvent être utilisées par les workflows dans n’importe quel dépôt. Lorsqu’une action se trouve dans un référentiel privé, les paramètres du référentiel déterminent si l’action est disponible uniquement dans le même référentiel ou également dans d’autres référentiels appartenant aux mêmes utilisateur ou organisation. Pour plus d’informations, consultez « Gestion des paramètres de GitHub Actions pour un dépôt ».

Exemple utilisant une action publique

Cet exemple montre comment votre nouvelle action publique peut être exécutée à partir d’un dépôt externe.

Copiez le code YAML suivant dans un nouveau fichier à l’emplacement .github/workflows/main.yml, puis mettez à jour la ligne uses: octocat/hello-world-javascript-action@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b avec votre nom d’utilisateur et le nom du dépôt public que vous avez créé ci-dessus. Vous pouvez également remplacer l’entrée who-to-greet par votre nom.

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 }}"

Lorsque ce workflow sera déclenché, l’exécuteur téléchargera l’action hello-world-javascript-action à partir de votre dépôt public, puis l’exécutera.

Exemple utilisant une action privée

Copiez le code du workflow dans un fichier .github/workflows/main.yml du dépôt de votre action. Vous pouvez également remplacer l’entrée who-to-greet par votre nom.

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 }}"

Dans votre dépôt, cliquez sur l’onglet Actions, puis sélectionnez la dernière exécution du workflow. Sous Travaux ou dans le graphe de visualisation, cliquez sur A job to say hello.

Cliquez sur Hello world action step et vous devriez voir « Hello Mona the Octocat » ou le nom que vous avez utilisé pour l’entrée who-to-greet imprimée dans le journal. Pour voir l’horodatage, cliquez sur Obtenir l’heure de la sortie.

Dépôts de modèles pour créer des actions JavaScript

GitHub fournit des dépôts de modèles pour créer des actions JavaScript et TypeScript. Vous pouvez utiliser ces modèles pour commencer rapidement à créer une action qui inclut des tests, un linting et d’autres pratiques recommandées.

• Dépôt de modèles javascript-action
• Dépôt de modèles typescript-action

Exemples d’actions JavaScript sur GitHub.com

Vous pouvez trouver de nombreux exemples d’actions JavaScript sur GitHub.com.

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