# Création d’une action JavaScript

Dans ce tutoriel, vous apprendrez à créer une action JavaScript à l'aide de la boîte à outils Actions.

## 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](https://github.com/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.

> \[!WARNING]
> Lors de la création de flux de travail et d’actions, vous devez toujours déterminer si votre code pourrait exécuter des entrées non fiables provenant de personnes malveillantes potentielles. Certains contextes doivent être traités comme des entrées non fiables, car un attaquant peut insérer son propre contenu malveillant. Pour plus d’informations, consultez « [Informations de référence sur l’utilisation sécurisée](/fr/enterprise-cloud@latest/actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections) ».

## 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](/fr/enterprise-cloud@latest/repositories/creating-and-managing-repositories/creating-a-new-repository) ».

3. Clonez votre dépôt sur votre ordinateur. Pour plus d’informations, consultez « [Clonage d’un dépôt](/fr/enterprise-cloud@latest/repositories/creating-and-managing-repositories/cloning-a-repository) ».

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

   ```shell copy
   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 copy
   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](/fr/enterprise-cloud@latest/actions/creating-actions/metadata-syntax-for-github-actions) ».

```yaml copy
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 sortie`time`. Il indique également à l’exécuteur d’actions comment exécuter cette action JavaScript.

## Ajouter des paquets d'ensemble d'outils 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`](https://github.com/actions/toolkit/tree/main/packages/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`](https://github.com/actions/toolkit/tree/main/packages/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](https://github.com/actions/toolkit).

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

```shell copy
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 fournissez des informations contextuelles sur l’événement webhook, les références Git, le flux de travail, l’action et la personne qui a déclenché le flux de travail. 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.

```javascript copy
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 provoquée dans l’exemple `index.js` ci-dessus, `core.setFailed(error.message);` utilise le paquet [`@actions/core`](https://github.com/actions/toolkit/tree/main/packages/core) de l’outil d’actions pour enregistrer un message et définir un code de sortie d’échec. Pour plus d’informations, consultez « [Définition des codes de sortie pour les actions](/fr/enterprise-cloud@latest/actions/creating-actions/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.

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

## Valider, baliser et envoyer 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`.

Vérifier votre répertoire `node_modules` peut entraîner des problèmes. Vous pouvez également utiliser des outils tels que [`rollup.js`](https://github.com/rollup/rollup) ou [`@vercel/ncc`](https://github.com/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 copy
   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 copy
   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 :

```text
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é ou interne, 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 organisation ou entreprise. Pour plus d’informations, consultez « [Gestion des paramètres de GitHub Actions pour un référentiel](/fr/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) ».

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

```yaml copy
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.

```yaml copy
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@v6

      - 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`](https://github.com/actions/javascript-action)
* [Dépôt de modèles `typescript-action`](https://github.com/actions/typescript-action)

## Exemples d’actions JavaScript sur GitHub.com

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

* [DevExpress/testcafe-action](https://github.com/DevExpress/testcafe-action)
* [duckduckgo/privacy-configuration](https://github.com/duckduckgo/privacy-configuration)