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 16.x, qui inclut npm.

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

2. Créez un dépôt public sur votre instance GitHub Enterprise Server 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 « Metadata syntax for GitHub Actions ».

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: 'node16'
  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: 'node16'
  main: '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
npm install @actions/github

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

Vous devez maintenant voir un répertoire node_modules avec les modules que vous venez d’installer, et un fichier package-lock.json comprenant les dépendances du module installé et les versions de chaque module installé.

É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é index.js en utilisant le code suivant.

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

Commiter, étiqueter et pousser (push) votre action dans GitHub

GitHub Enterprise Server télécharge chaque action exécutée dans un workflow au moment du runtime, et l’exécute en tant que package complet de code avant que vous puissiez utiliser des commandes de workflow comme run pour interagir avec la machine de l’exécuteur. Cela signifie que vous devez inclure toutes les dépendances de package qui sont nécessaires pour exécuter le code JavaScript. Vous devrez effectuer le check-in des packages core et github du kit de ressources dans le dépôt de votre action.

À partir de votre terminal, commitez vos fichiers action.yml, index.js, node_modules, package.json, package-lock.json et README.md. Si vous avez ajouté un fichier .gitignore qui liste node_modules, vous devez supprimer cette ligne pour commiter le répertoire node_modules.

Il est recommandé d’ajouter également une étiquette de version pour les versions de votre action. Pour plus d’informations sur le versioning de votre action, consultez « À propos des actions personnalisées ».

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

Le check-in de votre répertoire node_modules peut entraîner des problèmes. Vous pouvez également utiliser un outil appelé @vercel/ncc pour compiler votre code et vos modules dans un fichier utilisé pour la distribution.

1. Installez vercel/ncc en exécutant cette commande dans votre terminal.

   npm i -g @vercel/ncc

2. Compilez votre fichier index.js.

   ncc build index.js --license licenses.txt

   Vous verrez un nouveau fichier dist/index.js avec votre code et les modules compilés. Vous verrez également un fichier dist/licenses.txt contenant toutes les licences de node_modules que vous utilisez.

3. Modifiez le mot clé main dans votre fichier action.yml pour utiliser le nouveau fichier dist/index.js.

   main: 'dist/index.js'

4. Si vous avez déjà effectué le check-in de votre répertoire node_modules, supprimez-le.

   rm -rf node_modules/*

5. À partir de votre terminal, commitez les mises à jour de vos fichiers action.yml, dist/index.js et 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
   

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 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@v1.1 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]

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

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

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