Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.
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.
Warnung: Beim Erstellen von Workflows und Aktionen solltest du immer überprüfen, ob dein Code gegebenenfalls nicht vertrauenswürdige Eingaben von Angreifern ausführen kann. 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.
-
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.
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 Enterprise Server 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.
-
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 begleitendedist/licenses.txt
-Datei mit allen Lizenzen dernode_modules
, die du verwendest. -
Ändere das
main
-Schlüsselwort in deineraction.yml
-Datei so, dass die neuedist/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
undnode_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 oder internen 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 derselben Organisation bzw. desselben Unternehmens befinden. Weitere Informationen findest du unter Verwalten von GitHub Actions-Einstellungen für ein Repository.
Hinweis: GitHub Actions auf GitHub Enterprise Server verfügt möglicherweise nur über eingeschränkten Zugriff auf Aktionen auf der GitHub.com oder im GitHub Marketplace. Weitere Informationen findest du unter Verwalten des Zugriffs auf Aktionen in GitHub.com, oder wende dich an dendie GitHub Enterprise-Websiteadministratorin.
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@v1.1
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@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 }}"
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-Beispielaktionen unter GitHub.com
JavaScript-Beispielaktionen findest du unter GitHub.com.