Creating a JavaScript action (Erstellen einer JavaScript-Aktion)

Einführung

In dieser Anleitung erfährst du mehr über die grundlegenden Komponenten, die benötigt werden, um eine paketierte Docker-Container-Aktion zu erstellen und zu verwenden. Diese Anleitung fokussiert jene Komponenten, welche zum Paketieren der Aktion benötigt werden. Daher hat der Aktions-Code nur minimale Funktionalität. Die Aktion schreibt „Hello World“ in die Logs oder "Hello [who-to-greet]" wenn du einen benutzerdefinierten Namen angibst.

Diese Anleitung verwendet das Node.js Modul des GitHub Actions-Toolkits, um die Entwicklung zu beschleunigen. Weitere Informationen findest du im Repository für Aktionen/Toolkits.

Nach dem Abschluss dieses Projekts solltest du verstehen, wie du deine eigene JavaScript-Aktion erstellen und sie in einem Workflow testen kannst.

Um sicherzustellen, dass deine JavaScript-Aktionen mit allen GitHub-gehosteten Runnern (Ubuntu, Windows und macOS) kompatibel sind, sollte der von dir geschriebene paketierte JavaScript-Code reines JavaScript sein und nicht von anderen Binärdateien abhängig sein. JavaScript-Aktionen werden direkt auf dem Runner ausgeführt und verwenden Binärdateien, die bereits im Runner-Image vorhanden sind.

Voraussetzungen

Bevor du beginnst, musst du Node.js herunterladen und ein öffentliches GitHub-Repository erstellen.

1. Laden Sie die Anwendung Node.js 20.x (enthält npm) herunter, und installieren Sie sie.

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

2. Erstelle ein neues öffentliches Repository in GitHub und nenne es „hello-world-javascript-action“. Weitere Informationen finden Sie unter Ein neues Repository erstellen.

3. Klone dein Repository auf deinen Computer. Weitere Informationen finden Sie unter Ein Repository klonen.

4. Gehe in deinem Terminal zum Verzeichnisse deines neuen Repositorys.

   Shell

   cd hello-world-javascript-action
   

5. Initialisiere im Terminal das Verzeichnis mit npm, um eine package.json-Datei zu generieren.

   Shell

   npm init -y
   

Eine Datei für die Metadaten der Aktion erstellen

Erstelle mit dem folgenden Beispielcode eine Datei namens action.yml im Verzeichnis hello-world-javascript-action. Weitere Informationen finden Sie unter Metadatensyntax für 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: 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

Diese Datei definiert die Eingabe für who-to-greet und die Ausgabe für time. Sie teilt dem Aktionsrunner auch mit, wie diese JavaScript-Aktion gestartet wird.

Toolkit-Pakete für Aktionen hinzufügen

Das Toolkit für Aktionen ist eine Node.js-Paketsammlung, mit der du JavaScript-Aktionen schnell und konsistenter erstellen kannst.

Das Toolkitpaket @actions/core bietet eine Schnittstelle zu Befehlen, Eingabe- und Ausgabevariablen, Beendigungsstatus und Debugnachrichten des Workflows.

Das Toolkit bietet auch ein @actions/github-Paket, das einen authentifizierten Octokit-REST-Client und Zugriff auf GitHub Actions-Kontexte zurückgibt.

Das Toolkit bietet mehr als die Pakete core und github. Weitere Informationen findest du im Repository für Aktionen/Toolkits.

Installiere am Terminal die Pakete core und github des Aktionstoolkits.

npm install @actions/core @actions/github

npm install @actions/core @actions/github

Nun sollten das Verzeichnis node_modules und die Datei package-lock.json angezeigt werden, mit der alle installierten Abhängigkeiten und deren Versionen nachverfolgt werden. Du solltest das Verzeichnis node_modules nicht in dein Repository committen.

Aktions-Code schreiben

Diese Aktion verwendet das Toolkit, um die in der Metadatendatei der Aktion erforderliche Eingabevariable who-to-greet abzurufen, und gibt „Hello [who-to-greet]“ in einer Debuggingmeldung im Protokoll aus. Als Nächstes ruft das Skript die aktuelle Zeit ab und legt sie als eine Ausgabevariable fest, die von später in einem Auftrag ausgeführten Aktionen verwendet werden kann.

GitHub Actions stellt Kontextinformationen zum Webhook-Ereignis, zu den Git-Refs, zum Workflow, zur Aktion und zur Person bereit, die den Workflow ausgelöst hat. Um auf die Kontextinformationen zuzugreifen, kannst du das github-Paket verwenden. Die von Ihnen geschriebene Aktion gibt die Webhook-Ereignisnutzdaten im Protokoll aus.

Füge mit dem folgenden Code eine neue Datei namens src/index.js hinzu.

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);
}

Wenn im obigen index.js-Beispiel ein Fehler ausgelöst wird, verwendet core.setFailed(error.message); das Aktionstoolkitpaket @actions/core, um eine Nachricht zu protokollieren und einen Exitcode mit Fehler festzulegen. Weitere Informationen finden Sie unter Setting exit codes for actions (Festlegen von Exitcodes für Aktionen).

Eine README erstellen

Du kannst eine README-Datei erstellen, um Person zu zeigen, wie sie deine Aktion verwenden sollen. Ein README ist sehr hilfreich, wenn Du planst, Deine Aktion öffentlich bereitzustellen, aber es ist auch eine großartige Möglichkeit, Dich oder Dein Team daran zu erinnern, wie die Aktion zu verwenden ist.

Erstelle in deinem hello-world-javascript-action-Verzeichnis eine README.md-Datei, mit der die folgenden Informationen angegeben werden:

• Eine ausführliche Beschreibung, wozu die Aktion dient
• Erforderliche Eingabe- und Ausgabeargumente
• Optionale Eingabe- und Ausgabeargumente
• Geheimnisse, die von der Aktion verwendet werden
• Umgebungsvariablen, die von der Aktion verwendet werden
• Ein Beispiel für die Verwendung Ihrer Aktion in einem 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
```

Committen, Taggen und Pushen deiner Aktion

GitHub lädt alle Aktionen herunter, die zur Runtime in einem Workflow ausgeführt werden, und führt sie als komplettes Codepaket aus, bevor du Workflowbefehle wie run zum Interagieren mit dem Runnercomputer verwenden kannst. Folglich musst du alle zum Ausführen des JavaScript-Codes erforderlichen Paketabhängigkeiten einschließen. Beispiel: Diese Aktion verwendet @actions/core- und @actions/github-Pakete.

Das Einchecken deines node_modules-Verzeichnisses kann zu Problemen führen. Alternativ kannst du Tools wie rollup.js oder @vercel/ncc verwenden, um Code und Abhängigkeiten in einer Datei für die Verteilung zu kombinieren.

1. Installiere rollup und die zugehörigen Plug-Ins, indem du diesen Befehl in deinem Terminal ausführst.

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

2. Erstelle im Stammverzeichnis deines Repositorys eine neue Datei namens rollup.config.js mit dem folgenden Code.

   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. Kompiliere deine dist/index.js-Datei.

   rollup --config rollup.config.js

   Eine neue dist/index.js-Datei mit deinem Code und allen Abhängigkeiten wird angezeigt.

4. Committe die Updates über dein Terminal.

   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
   

Wenn du deinen Code committest und pushst, sollte dein aktualisiertes Repository folgendermaßen aussehen:

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

Deine Aktion in einem Workflow testen

Nun bist du bereit, deine Aktion in einem Workflow zu testen.

Öffentliche Aktionen können von Workflows in jedem beliebigen Repository verwendet werden. Wenn sich eine Aktion in einem privaten Repository befindet, bestimmen die Repositoryeinstellungen, ob die Aktion nur innerhalb desselben Repositorys oder auch für andere Repositorys verfügbar ist, die sich im Besitz desselben Benutzers oder derselben Organisation befinden. Weitere Informationen finden Sie unter Verwalten von GitHub Actions-Einstellungen für ein Repository.

Beispiel mit einer öffentlichen Aktion

Dieses Beispiel veranschaulicht, wie deine neue öffentliche Aktion aus einem externen Repository heraus ausgeführt werden kann.

Kopiere den folgende YAML-Code in eine neue Datei in .github/workflows/main.yml, und aktualisiere die Zeile uses: octocat/hello-world-javascript-action@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b mit deinem Benutzernamen und dem Namen des öffentlichen Repositorys, das du weiter oben erstellt hast. Du kannst auch die Eingabe für who-to-greet durch deinen Namen ersetzen.

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

Wenn dieser Workflow ausgelöst wird, lädt der Runner die Aktion hello-world-javascript-action aus deinem öffentlichen Repository herunter und führt sie aus.

Beispiel mit einer privaten Aktion

Kopiere den Workflowcode in eine .github/workflows/main.yml-Datei im Repository deiner Aktion. Du kannst auch die Eingabe für who-to-greet durch deinen Namen ersetzen.

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

Klicke in deinem Repository auf die Registerkarte Aktionen, und wähle die neueste Workflowausführung aus. Klicke unter Aufträge oder im Visualisierungsdiagramm auf A job to say hello.

Wähle Hello world action step aus. Im Protokoll sollten „Hello Mona the Octocat“ oder der von dir für die who-to-greet-Eingabe verwendete Name ausgegeben werden. Um den Zeitstempel anzuzeigen, klicke auf Ausgabezeit abrufen.

Vorlagenrepositorys zum Erstellen von JavaScript-Aktionen

GitHub stellt Vorlagenrepositorys zum Erstellen von JavaScript- und TypeScript-Aktionen bereit. Du kannst diese Vorlagen verwenden, um schnell mit dem Erstellen einer neuen Aktion zu beginnen, die Tests, Linten und andere empfohlene Methoden umfasst.

• javascript-action-Vorlagenrepository
• typescript-action-Vorlagenrepository

JavaScript-Beispielaktionen unter GitHub.com

JavaScript-Beispielaktionen findest du unter GitHub.com.

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