Skip to content
Hands-on IT IT Drills

Day 13: A JavaScript Action of Your Own

Goal: Write a JavaScript action healthcheck that polls a URL until it responds – without dependencies, using only Node.js. Test it locally, use it in a workflow and call it via a Git tag from another workflow. · Duration: approx. 75 min · Prerequisite: Day 12

Briefing

  • A JavaScript action consists of action.yml with runs.using: node24 and a JS file. The runner ships with Node.js.
  • The interface is environment variables and files:
    • input url → variable INPUT_URL
    • output → line name=wert in the file $GITHUB_OUTPUT
    • summary → Markdown in $GITHUB_STEP_SUMMARY
    • error → non-zero exit code, annotation with ::error::
  • The package @actions/core wraps exactly that. For a small action you can do without it – then there is no node_modules and no build step.
 with: url: http://…/healthz  ─► INPUT_URL ─► index.js ─► fetch until 2xx
                                                       ├► $GITHUB_OUTPUT  antwort=ok
                                                       ├► $GITHUB_STEP_SUMMARY
                                                       └► ::error:: + exit 1

Drill 1: The 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 – polls a URL until it responds with 2xx
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
  • Inputs arrive in uppercase with the prefix INPUT_: versuche becomes INPUT_VERSUCHE.
  • fetch is built into Node.js. Connection errors end up in the catch, their code (e.g. ECONNREFUSED) is in err.cause.code.
  • ::error title=…::Text is a workflow command: the runner turns the line into an annotation on the run.
  • process.exitCode = 1 makes Node exit with an error – the step turns red.

Save your progress? Sign up for free

Drill 2: Testing locally

You don’t have Node.js on the VM; a container is enough. The action polls notes-api in the k3s from Day 11:

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

Expected:

Versuch 1: 200 0.5.2
antwort=0.5.2

The first time, Docker downloads the node:24-alpine image beforehand.

  • --network host: the container sees the VM’s localhost.
  • GITHUB_OUTPUT=/dev/stdout: instead of to a file, the action writes its outputs to the screen – so you see what it would report to the workflow.

And if nothing responds?

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: $?"

Expected:

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

Save your progress? Sign up for free

Drill 3: In the workflow

The smoke job in ci.yml starts notes-api and so far waits with sleep 1. The action waits exactly as long as necessary. For that, the job needs a checkout – the action lives in the repository. The new version of the job (replace it with the editor, everything else stays):

  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
  • The process from “Starten” keeps running in the background, even after the step has ended – until the job ends.
  • steps.gesund.outputs.antwort is the output that index.js wrote to $GITHUB_OUTPUT.

With the ID from gh run list --workflow ci.yml --limit 1, as soon as the run is finished:

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

Expected (timestamps shortened):

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

notes-api was fast enough for the first attempt. If a service starts more slowly, lines with ECONNREFUSED appear before it – and the action waits instead of guessing a fixed time like sleep 1.

Save your progress? Sign up for free

Drill 4: Calling it via a tag

Other workflows – in other repositories too – call the action via owner, repository, path and ref. A tag turns it into a fixed version:

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

After the rollout, deploy.yml checks whether the new version responds. A checkout is not necessary – the runner downloads the action itself. The whole file:

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, path to the action, Git ref. Without a path (<du>/healthcheck@v1), action.yml would sit in the root directory of a repository of its own – that is how you publish actions in the Marketplace.
  • Your own runner executes the JS action with the Node.js it ships itself. You don’t need to install anything on the VM.

Approve as on Day 11. As soon as the run is finished:

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

Expected (timestamp shortened):

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

Save your progress? Sign up for free

Checkpoint

ls .github/actions/healthcheck

Expected:

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

Expected:

success
0.5.1

Challenge

The action should optionally check what responds: an input erwartet – if the text does not match, the attempt counts as a failure. deploy.yml passes ${{ inputs.version }}.

Hint: INPUT_ERWARTET, empty means “don’t care”. After the change, a new tag, e.g. v0.6.0-rc.4, and switch deploy.yml to it.

Solution

In action.yml under inputs: (with the editor):

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

In index.js, two places. At the top:

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

And the condition:

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

In deploy.yml, extend the step and change the tag:

        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

Approve, then:

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

Expected (depending on how quickly the old pods are gone):

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

If an old pod still responds with 0.5.1, you see another attempt – the action waits until the new version really responds.

Save your progress? Sign up for free

Enterprise Note

  • @actions/core and bundling: Larger actions use the toolkit (@actions/core, @actions/github) and bundle everything with ncc or esbuild into a single file dist/index.js that is committed to the repository. The runner does not run npm install.
  • Docker instead of JS actions: runs.using: docker starts a container – any language is possible, but only on Linux runners and with a wait for the image.
  • Versions: Published actions get tags such as v1.2.3 and a mutable v1. Users still pin the SHA (Day 9).
  • Internal actions: In organizations, an internal repository can provide actions for all other repositories (Settings → Actions → Access) without making them public.