Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 13: Eine eigene JavaScript-Action

Ziel: Eine JavaScript-Action healthcheck schreiben, die eine URL abfragt, bis sie antwortet – ohne Abhängigkeiten, nur mit Node.js. Lokal testen, im Workflow nutzen und über ein Git-Tag aus einem anderen Workflow aufrufen. · Dauer: ca. 75 min · Voraussetzung: Tag 12

Briefing

  • Eine JavaScript-Action besteht aus action.yml mit runs.using: node24 und einer JS-Datei. Der Runner bringt Node.js mit.
  • Die Schnittstelle sind Umgebungsvariablen und Dateien:
    • Eingabe url → Variable INPUT_URL
    • Output → Zeile name=wert in die Datei $GITHUB_OUTPUT
    • Zusammenfassung → Markdown in $GITHUB_STEP_SUMMARY
    • Fehler → Exit-Code ungleich 0, Annotation mit ::error::
  • Das Paket @actions/core verpackt genau das. Für eine kleine Action geht es ohne – dann gibt es kein node_modules und keinen Build-Schritt.
 with: url: http://…/healthz  ─► INPUT_URL ─► index.js ─► fetch, bis 2xx
                                                       ├► $GITHUB_OUTPUT  antwort=ok
                                                       ├► $GITHUB_STEP_SUMMARY
                                                       └► ::error:: + Exit 1

Drill 1: Die Action

cd ~/gha-lab/notes-actions
mkdir -p .github/actions/healthcheck
cat > .github/actions/healthcheck/action.yml <<'EOF'
name: healthcheck
description: Fragt eine URL ab, bis sie mit 2xx antwortet
inputs:
  url:
    description: Adresse, z. B. http://localhost:8090/healthz
    required: true
  versuche:
    description: Wie oft fragen, einmal pro Sekunde
    default: "10"
outputs:
  antwort:
    description: Text der Antwort
runs:
  using: node24
  main: index.js
EOF
cat > .github/actions/healthcheck/index.js <<'EOF'
// healthcheck – fragt eine URL ab, bis sie mit 2xx antwortet
const fs = require('node:fs');

const url = process.env.INPUT_URL;
const versuche = Number(process.env.INPUT_VERSUCHE || '10');

async function main() {
  for (let i = 1; i <= versuche; i++) {
    try {
      const res = await fetch(url);
      const text = (await res.text()).trim();
      console.log(`Versuch ${i}: ${res.status} ${text}`);
      if (res.ok) {
        fs.appendFileSync(process.env.GITHUB_OUTPUT, `antwort=${text}\n`);
        fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${url} antwortet: ${text}\n`);
        return;
      }
    } catch (err) {
      console.log(`Versuch ${i}: ${err.cause?.code || err.message}`);
    }
    await new Promise((r) => setTimeout(r, 1000));
  }
  console.log(`::error title=healthcheck::${url} antwortet nicht nach ${versuche} Versuchen`);
  process.exitCode = 1;
}

main();
EOF
  • Eingaben kommen in Großbuchstaben mit Präfix INPUT_: versuche wird zu INPUT_VERSUCHE.
  • fetch ist in Node.js eingebaut. Verbindungsfehler landen im catch, ihr Code (z. B. ECONNREFUSED) steht in err.cause.code.
  • ::error title=…::Text ist ein Workflow-Kommando: Der Runner macht aus der Zeile eine Annotation am Lauf.
  • process.exitCode = 1 lässt Node mit Fehler enden – der Step wird rot.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Lokal testen

Node.js hast du auf der VM nicht, ein Container genügt. Die Action fragt notes-api im k3s von Tag 11 ab:

docker run --rm --network host -v "$PWD":/w -w /w \
  -e INPUT_URL=http://localhost:30081/version \
  -e GITHUB_OUTPUT=/dev/stdout -e GITHUB_STEP_SUMMARY=/dev/null \
  node:24-alpine node .github/actions/healthcheck/index.js

Erwartet:

Versuch 1: 200 0.5.2
antwort=0.5.2

Beim ersten Mal lädt Docker vorher das Image node:24-alpine.

  • --network host: Der Container sieht localhost der VM.
  • GITHUB_OUTPUT=/dev/stdout: Statt in eine Datei schreibt die Action ihre Outputs auf den Bildschirm – so siehst du, was sie dem Workflow melden würde.

Und wenn nichts antwortet?

docker run --rm --network host -v "$PWD":/w -w /w \
  -e INPUT_URL=http://localhost:30099/ -e INPUT_VERSUCHE=2 \
  -e GITHUB_OUTPUT=/dev/stdout -e GITHUB_STEP_SUMMARY=/dev/null \
  node:24-alpine node .github/actions/healthcheck/index.js; echo "Exit: $?"

Erwartet:

Versuch 1: ECONNREFUSED
Versuch 2: ECONNREFUSED
::error title=healthcheck::http://localhost:30099/ antwortet nicht nach 2 Versuchen
Exit: 1

Fortschritt speichern? Kostenlos registrieren

Drill 3: Im Workflow

Der Job smoke in ci.yml startet notes-api und wartet bisher mit sleep 1. Die Action wartet genau so lange wie nötig. Der Job braucht dafür einen Checkout – die Action liegt im Repository. Die neue Fassung des Jobs (mit dem Editor ersetzen, alles andere bleibt):

  smoke:
    needs: build
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: notes-api-linux-amd64
      - name: Starten
        run: |
          chmod +x notes-api-linux-amd64
          NOTES_API_KEY=lab-api-key-123 PORT=8090 ./notes-api-linux-amd64 &
      - id: gesund
        uses: ./.github/actions/healthcheck
        with:
          url: http://localhost:8090/healthz
      - env:
          ANTWORT: ${{ steps.gesund.outputs.antwort }}
        run: echo "notes-api sagt $ANTWORT"
git add .github
git commit -qam "ci: healthcheck-Action im Smoke-Test"
git push -q
  • Der Prozess aus „Starten“ läuft im Hintergrund weiter, auch nach dem Ende des Steps – bis der Job endet.
  • steps.gesund.outputs.antwort ist der Output, den index.js nach $GITHUB_OUTPUT geschrieben hat.

Mit der ID aus gh run list --workflow ci.yml --limit 1, sobald der Lauf fertig ist:

gh run view <ID> --log | grep -E 'smoke.*Z (Versuch|notes-api sagt)'

Erwartet (Zeitstempel gekürzt):

smoke   Run ./.github/actions/healthcheck   ... Versuch 1: 200 ok
smoke   Run echo "notes-api sagt $ANTWORT"  ... notes-api sagt ok

notes-api war schnell genug für den ersten Versuch. Startet ein Dienst langsamer, stehen davor Zeilen mit ECONNREFUSED – und die Action wartet, statt wie sleep 1 eine feste Zeit zu raten.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Über ein Tag aufrufen

Andere Workflows – auch in anderen Repositorys – rufen die Action über Besitzer, Repository, Pfad und Ref auf. Ein Tag macht daraus eine feste Version:

git tag v0.6.0-rc.3
git push -q origin v0.6.0-rc.3

deploy.yml prüft nach dem Rollout, ob die neue Version antwortet. Ein Checkout ist nicht nötig – der Runner lädt die Action selbst. Die ganze Datei:

cat > .github/workflows/deploy.yml <<'EOF'
name: deploy
on:
  workflow_dispatch:
    inputs:
      version:
        description: Image-Tag, z. B. 0.5.1
        required: true

permissions:
  contents: read

concurrency:
  group: deploy-produktion
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: [self-hosted, lab]
    environment:
      name: produktion
      url: http://localhost:30081/version
    env:
      IMAGE: ghcr.io/${{ github.repository_owner }}/notes-api:${{ inputs.version }}
    steps:
      - name: Version setzen
        run: kubectl -n notes set image deployment/notes-api notes-api="$IMAGE"
      - name: Rollout abwarten
        run: kubectl -n notes rollout status deployment/notes-api --timeout=60s
      - name: Antwortet die neue Version?
        uses: OWNER/notes-actions/.github/actions/[email protected]
        with:
          url: http://localhost:30081/version
      - name: Zurückrollen
        if: failure()
        run: kubectl -n notes rollout undo deployment/notes-api
EOF
sed -i "s|OWNER/|$(gh api user --jq .login)/|" .github/workflows/deploy.yml
git commit -qam "deploy: healthcheck nach dem Rollout"
git push -q
gh workflow run deploy.yml -f version=0.5.1
  • <du>/notes-actions/.github/actions/[email protected]: Repository, Pfad zur Action, Git-Ref. Ohne Pfad (<du>/healthcheck@v1) läge action.yml im Hauptverzeichnis eines eigenen Repositorys – so veröffentlicht man Actions im Marketplace.
  • Dein eigener Runner führt die JS-Action mit dem Node.js aus, das er selbst mitbringt. Auf der VM musst du nichts installieren.

Freigeben wie an Tag 11. Sobald der Lauf fertig ist:

gh run view <ID> --log | grep -E 'Z Versuch'

Erwartet (Zeitstempel gekürzt):

deploy  Antwortet die neue Version? ... Versuch 1: 200 0.5.1

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

ls .github/actions/healthcheck

Erwartet:

action.yml
index.js
gh run list --workflow deploy.yml --limit 1 --json conclusion --jq '.[0].conclusion'
curl -s localhost:30081/version

Erwartet:

success
0.5.1

Challenge

Die Action soll optional prüfen, was antwortet: Eine Eingabe erwartet – stimmt der Text nicht, zählt der Versuch als Fehlschlag. deploy.yml übergibt ${{ inputs.version }}.

Hinweis: INPUT_ERWARTET, leer heißt „egal“. Nach der Änderung ein neues Tag, z. B. v0.6.0-rc.4, und deploy.yml darauf umstellen.

Lösung

In action.yml unter inputs: (mit dem Editor):

  erwartet:
    description: Erwarteter Antworttext, leer = egal
    default: ""

In index.js zwei Stellen. Oben:

const erwartet = process.env.INPUT_ERWARTET || '';

Und die Bedingung:

      if (res.ok && (erwartet === '' || text === erwartet)) {

In deploy.yml den Step erweitern und das Tag ändern:

        uses: <du>/notes-actions/.github/actions/[email protected]
        with:
          url: http://localhost:30081/version
          erwartet: ${{ inputs.version }}
git commit -qam "healthcheck: erwarteter Text"
git push -q
git tag v0.6.0-rc.4
git push -q origin v0.6.0-rc.4
gh workflow run deploy.yml -f version=0.5.2

Freigeben, dann:

gh run view <ID> --log | grep -E 'Z Versuch'

Erwartet (je nachdem, wie schnell die alten Pods weg sind):

deploy  Antwortet die neue Version? ... Versuch 1: 200 0.5.2

Antwortet noch ein alter Pod mit 0.5.1, siehst du einen weiteren Versuch – die Action wartet, bis wirklich die neue Version antwortet.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • @actions/core und Bündeln: Größere Actions nutzen das Toolkit (@actions/core, @actions/github) und bündeln alles mit ncc oder esbuild in eine Datei dist/index.js, die mit ins Repository kommt. Der Runner führt kein npm install aus.
  • Docker- statt JS-Actions: runs.using: docker startet einen Container – jede Sprache ist möglich, aber nur auf Linux-Runnern und mit Wartezeit fürs Image.
  • Versionen: Veröffentlichte Actions bekommen Tags wie v1.2.3 und ein bewegliches v1. Nutzer pinnen trotzdem den SHA (Tag 9).
  • Interne Actions: In Organisationen kann ein internes Repository Actions für alle anderen Repositorys bereitstellen (Settings → Actions → Access), ohne sie öffentlich zu machen.