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.

Warning

Bei der Erstellung von Workflows und Aktionen sollten Sie immer bedenken, ob Ihr Code nicht vertrauenswürdige Eingaben von möglichen Eindringlingen ausführen könnte. Bestimmte Kontexte sollten als nicht vertrauenswürdige Eingaben behandelt werden, da ein Angreifer seine eigenen schädlichen Inhalte einfügen könnte. Weitere Informationen findest du unter Sicherheitshärtung für GitHub Actions.

Voraussetzungen

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

Laden Sie Node.js 20.x, einschließlich npm, herunter und installieren Sie es.

https://nodejs.org/en/download/
Erstelle ein neues öffentliches Repository in GitHub und nenne es „hello-world-javascript-action“. Weitere Informationen findest du unter Ein neues Repository erstellen.
Klone dein Repository auf deinen Computer. Weitere Informationen findest du unter Ein Repository klonen.
Gehe in deinem Terminal zum Verzeichnisse deines neuen Repositorys.
Shell
```
cd hello-world-javascript-action
```
```
cd hello-world-javascript-action
```
Initialisiere im Terminal das Verzeichnis mit npm, um eine package.json-Datei zu generieren.
Shell
```
npm init -y
```
```
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.

YAML

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.

Shell

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.

JavaScript

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

Markdown

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

Shell

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.

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

npm i -g @vercel/ncc
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.
Ändere das main-Schlüsselwort in deiner action.yml-Datei so, dass die neue dist/index.js-Datei verwendet wird.

main: 'dist/index.js'
Wenn du das node_modules-Verzeichnis bereits eingecheckt hast, entferne es.

rm -rf node_modules/*

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

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.

YAML

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

YAML

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-Beispielaktionen unter GitHub.com

JavaScript-Beispielaktionen findest du unter GitHub.com.

Creating a JavaScript action (Erstellen einer JavaScript-Aktion)

Erstellen einer App

In diesem Artikel

Einführung

Voraussetzungen

Eine Datei für die Metadaten der Aktion erstellen

Toolkit-Pakete für Aktionen hinzufügen

Aktions-Code schreiben

Eine README erstellen

Committe, tagge und pushe deine Aktion auf GitHub

Deine Aktion in einem Workflow testen

Beispiel mit einer öffentlichen Aktion

Beispiel mit einer privaten Aktion

Vorlagenrepositorys zum Erstellen von JavaScript-Aktionen

JavaScript-Beispielaktionen unter GitHub.com