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 Node.js 20.x, einschließlich npm, herunter und installieren Sie es.

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

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

3. Klone dein Repository auf deinen Computer. Weitere Informationen findest du 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 findest du 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: '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: '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
npm install @actions/github

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

Jetzt solltest du ein node_modules-Verzeichnis mit den soeben installierten Modulen und eine package-lock.json-Datei mit den installierten Modulabhängigkeiten und den Versionen jedes installierten Moduls sehen.

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 index.js hinzu.

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

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 findest du 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 deiner 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'
```

Committe, tagge und pushe deine Aktion auf GitHub

GitHub lädt jede Aktion, die zur Laufzeit in einem Workflow ausgeführt wird, herunter und führt sie als komplettes Codepaket aus, bevor du Workflowbefehle wie run zur Interaktion mit dem Runnercomputer verwenden kannst. Folglich musst du alle zum Ausführen des JavaScript-Codes erforderlichen Paketabhängigkeiten einschließen. Du musst die Pakete core und github des Toolkits im Repository deiner Aktion einchecken.

Committe von deinem Terminal aus die Dateien action.yml, index.js, node_modules, package.json, package-lock.json und README.md. Wenn du eine .gitignore-Datei hinzugefügt hast, die node_modules auflistet, musst du diese Zeile entfernen, um das node_modules-Verzeichnis zu committen.

Es hat sich bewährt, auch ein Versions-Tag für Releases deiner Aktion hinzuzufügen. Weitere Informationen zur Versionsverwaltung deiner Aktion findest du unter Informationen zu benutzerdefinierten Aktionen.

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

Das Einchecken deines node_modules-Verzeichnisses kann zu Problemen führen. Alternativ dazu kannst du ein Tool namens @vercel/ncc verwenden, um deinen Code und deine Module in eine Datei zu kompilieren, die für die Verteilung verwendet wird.

1. Installiere vercel/ncc, indem du diesen Befehl an deinem Terminal ausführst.

   npm i -g @vercel/ncc

2. Kompiliere deine index.js-Datei.

   ncc build index.js --license licenses.txt

   Du siehst eine neue dist/index.js-Datei mit deinem Code und den kompilierten Modulen. Außerdem siehst du eine begleitende dist/licenses.txt-Datei mit allen Lizenzen der node_modules, die du verwendest.

3. Ändere das main-Schlüsselwort in deiner action.yml-Datei so, dass die neue dist/index.js-Datei verwendet wird.

   main: 'dist/index.js'

4. Wenn du das node_modules-Verzeichnis bereits eingecheckt hast, entferne es.

   rm -rf node_modules/*

5. Committe an deinem Terminal die Aktualisierungen in die Dateien action.yml, dist/index.js und 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
   

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 findest du 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]

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@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]

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

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

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