Note: GitHub Actions was available for GitHub Enterprise Server 2.22 as a limited beta. The beta has ended. GitHub Actions is now generally available in GitHub Enterprise Server 3.0 or later. For more information, see the GitHub Enterprise Server 3.0 release notes.
- For more information about upgrading to GitHub Enterprise Server 3.0 or later, see "Upgrading GitHub Enterprise Server."
- For more information about configuring GitHub Actions after you upgrade, see the documentation for GitHub Enterprise Server 3.0.
Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the 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 actions/toolkit.
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 Läufern (Ubuntu, Windows und macOS) kompatibel sind, sollte der von Dir geschriebene paketierte JavaScript-Code reines JavaScript sein und sich nicht auf andere Binärdateien verlassen. JavaScript-Aktionen werden direkt auf dem Läufer ausgeführt und verwenden Binärdateien, die bereits in der virtuellen Umgebung vorhanden sind.
Warning: When creating workflows and actions, you should always consider whether your code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert their own malicious content. For more information, see "Understanding the risk of script injections."
Vorrausetzungen
Before you begin, you'll need to download Node.js and create a public GitHub repository.
-
Lade die Anwendung Node.js 12.x, welche npm enthält, herunter, und installiere sie.
-
Create a new public repository on your GitHub Enterprise Server instance and call it "hello-world-javascript-action". Weitere Informationen finden Sie unter „Neues Repository erstellen“.
-
Clone Dein Repository auf Deinen Computer. Weitere Informationen findest Du unter „Ein Repository clonen“.
-
Gehe in Deinem Terminal zum Verzeichnisse Deines neuen Repositorys.
cd hello-world-javascript-action
-
From your terminal, initialize the directory with npm to generate a
package.json
file.npm init -y
Eine Datei für die Metadaten der Aktion erstellen
Create a new file named action.yml
in the hello-world-javascript-action
directory with the following example code. Weitere Informationen findest Du unter „Metadaten-Syntax für GitHub Actions“.
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
who-to-greet: # ID der Eingabe
description: 'Who to greet'
required: true
default: 'World'
outputs:
time: # ID der Ausgabe
description: 'The time we greeted you'
runs:
using: 'node12'
main: 'index.js'
Diese Datei definiert die Eingabe who-to-greet
und die Ausgabe time
. Sie gibt dem Action-Runner auch an, wie diese JavaScript-Aktion ausgeführt werden soll.
Toolkit-Pakete für Aktionen hinzufügen
Das Toolkit für Aktionen ist eine Node.js-Paketsammlung, mit der Sie JavaScript-Aktionen schnell und konsistenter erstellen können.
Das Toolkit-Paket @actions/core
enthält eine Schnittstelle für die Workflow-Befehle, Eingabe- und Ausgabevariablen, Exit-Status und Debugging-Meldungen.
Das Toolkit enthält zudem das Paket @actions/github
, das einen authentifizierten Octokit REST-Client und Zugriff auf GitHub Aktions-Kontexte bietet.
Das Toolkit bietet mehr als die Pakete core
und github
. Weitere Informationen findest Du im Repository actions/toolkit.
Installiere an Deinem Terminal die Pakete core
und github
des Toolkits für Aktionen.
npm install @actions/core
npm install @actions/github
Nun sollte das Verzeichnis node_modules
mit den soeben von Dir installierten Modulen und die Datei package-lock.json
mit den installierten Modulabhängigkeiten sowie die Version des jeweils installierten Moduls angezeigt werden.
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]“ im Protokoll in einer Debugging-Meldung 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 Paket github
verwenden. The action you'll write will print the webhook event payload to the log.
Füge eine neue Datei mit der Bezeichnung index.js
mit dem folgenden Code hinzu.
const core = require('@actions/core');
const github = require('@actions/github');
try {
// `who-to-greet` Eingabedaten, in der Metadaten-Datei der Aktion definiert
const nameToGreet = core.getInput('who-to-greet');
console.log(`Hello ${nameToGreet}!`);
const time = (new Date()).toTimeString();
core.setOutput("time", time);
// Hole die JSON Webhook Nutzlast fuer das Ereignis, das den Workflow angestossen hat
const payload = JSON.stringify(github.context.payload, undefined, 2)
console.log(`The event payload: ${payload}`);
} catch (error) {
core.setFailed(error.message);
}
Wenn im o. g. index.js
-Beispiel ein Fehler ausgegeben wird, nutzt core.setFailed(error.message);
das Aktions-Toolkit-Paket @actions/core
, um eine Meldung zu protokollieren und einen Fehler-Exit-Code festzulegen. Weitere Informationen findest Du unter "Exit Codes für Aktionen setzen."
Eine README erstellen
Sie können eine README-Datei erstellen, um Person dahingehend zu informieren, wie sie Ihre Aktion verwenden sollen. Eine README ist am hilfreichsten, wenn Sie vorhaben, Ihre Aktion öffentlich freizugeben. Zudem eignet sie sich dafür, Sie oder Ihr Team dahingehend zu erinnern, wie die Aktion verwendet wird.
Erstelle in Deinem Verzeichnis hello-world-javascript-action
eine Datei README.md
mit folgenden Informationen:
- Eine ausführliche Beschreibung, was die Aktion bewirkt.
- Erforderliche Eingabe- und Ausgabe-Argumente.
- Optionale Eingabe- und Ausgabe-Argumente.
- Geheimnisse, die in der Aktion benutzt werden.
- Umgebungsvariablen, die in der Aktion benutzt werden.
- Ein Beispiel für die Verwendung Deiner Aktion in einem Workflow.
# JavaScript-Aktion „Hello world“
Diese Aktion gibt „Hello World“ oder „Hello“ + den Namen einer Person aus, die im Protokoll gegrüßt werden soll.
## Inputs
## `who-to-greet`
**Required** The name of the person to greet. Der Standardwert lautet „World“.
## Outputs
## `time`
The time we greeted you.
Beispielverwendung
verwendet: actions/hello-world-javascript-action@v1.1
mit:
who-to-greet: 'Mona the Octocat'
Committe, tagge und pushe Deine Aktion auf GitHub
GitHub Enterprise Server lädt jede Aktion, die in einem Workflow während der Laufzeit ausgeführt wird, herunter und führt sie als komplettes Codepaket aus, bevor Du Workflow-Befehle wie run
zur Interaktion mit der Runner-Maschine verwenden kannst. Folglich musst Du alle zum Ausführen des JavaScript-Codes erforderlichen Paketabhängigkeiten einschließen. Sie müssen die Pakete core
und github
in das Repository Ihrer Aktion einchecken.
Committen Sie in Ihrem Terminal Ihre Dateien action.yml
, index.js
, node_modules
, package.json
, package-lock.json
und README.md
. Falls Sie eine .gitignore
-Datei hinzugefügt haben, die node_modules
auflistet, müssen Sie diese Zeile entfernen, um das Verzeichnis node_modules
zu committen.
Es hat sich bewährt, auch ein Versions-Tag für Releases Deiner Aktion hinzuzufügen. Weitere Informationen zur Versionierung Deiner Aktion findest Du unter "Informationen zu 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
Checking in your node_modules
directory can cause problems. As an alternative, you can use a tool called @vercel/ncc
to compile your code and modules into one file used for distribution.
-
Install
vercel/ncc
by running this command in your terminal.npm i -g @vercel/ncc
-
Kompiliere die Datei
index.js
.ncc build index.js --license licenses.txt
Es wird die neue Datei
dist/index.js
mit Deinem Code und den kompilierten Modulen angezeigt. You will also see an accompanyingdist/licenses.txt
file containing all the licenses of thenode_modules
you are using. -
Ändere das Schlüsselwort
main
in der Dateiaction.yml
so, dass die neue Dateidist/index.js
verwendet wird.main: 'dist/index.js'
-
Falls Du Dein Verzeichnis
node_modules
bereits eingecheckt hast, entferne es.rm -rf node_modules/*
-
Committe in Deinem Terminal die Updates für Deine Dateien
action.yml
,dist/index.js
undnode_modules
.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 sind Sie bereit, Ihre Aktion in einem Workflow zu testen. Wenn eine Aktion in einem privaten Repository vorliegt, kann die Aktion nur in Workflows im selben Repository verwendet werden. Öffentliche Aktionen können von Workflows aus jedem Repository verwendet werden.
Note: GitHub Actions on your GitHub Enterprise Server instance may have limited access to actions on GitHub.com or GitHub Marketplace. Weitere Informationen findest Du unter „Kommunikation zwischen selbst-gehosteten Runnern und GitHub“.
Beispiel mit einer öffentlichen Aktion
This example demonstrates how your new public action can be run from within an external repository.
Copy the following YAML into a new file at .github/workflows/main.yml
, and update the uses: octocat/hello-world-javascript-action@v1.1
line with your username and the name of the public repository you created above. Darüber hinaus können Sie die Eingabe who-to-greet
durch Ihren 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 }}"
When this workflow is triggered, the runner will download the hello-world-javascript-action
action from your public repository and then execute it.
Beispiel mit einer privaten Aktion
Kopieren Sie den Workflow-Code im Repository Ihrer Aktion in eine .github/workflows/main.yml
-Datei. Darüber hinaus können Sie die Eingabe who-to-greet
durch Ihren Namen ersetzen.
.github/workflows/main.yml
zu: [push]
Jobs:
hello_world_job:
läuft auf: ubuntu-latest
Name: Ein Job, um Hallo zu sagen
Schritte:
. Um die private Aktion dieses Repositorys zu verwenden,
- Sie müssen das Repository
- Name: Checkout
verwendet: Aktionen/checkout@v2
- Name: Hallo Welt-Aktionsschritt
verwendet: ./ - Verwendet eine Aktion im Root-Verzeichnis
ID: hallo
mit:
who-to-greet: 'Mona the Octocat'
. Verwenden Sie die Ausgabe aus dem 'Hallo' Schritt
- Name: Get the output time
run:{{ steps.hello.outputs.time }}echo
Klicke in Deinem Repository auf die Registerkarte Actions (Aktionen), und wähle die neueste Workflow-Ausführung aus. You should see "Hello Mona the Octocat" or the name you used for the who-to-greet
input and the timestamp printed in the log.