Day 13: A JavaScript Action of Your Own
Goal: Write a JavaScript action
healthcheckthat 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.ymlwithruns.using: node24and a JS file. The runner ships with Node.js. - The interface is environment variables and files:
- input
url→ variableINPUT_URL - output → line
name=wertin the file$GITHUB_OUTPUT - summary → Markdown in
$GITHUB_STEP_SUMMARY - error → non-zero exit code, annotation with
::error::
- input
- The package
@actions/corewraps exactly that. For a small action you can do without it – then there is nonode_modulesand 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
EOFcat > .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_:versuchebecomesINPUT_VERSUCHE. fetchis built into Node.js. Connection errors end up in thecatch, their code (e.g.ECONNREFUSED) is inerr.cause.code.::error title=…::Textis a workflow command: the runner turns the line into an annotation on the run.process.exitCode = 1makes 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.jsExpected:
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’slocalhost.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.antwortis the output thatindex.jswrote 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.3After 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.ymlwould 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/healthcheckExpected:
action.yml
index.js
gh run list --workflow deploy.yml --limit 1 --json conclusion --jq '.[0].conclusion'
curl -s localhost:30081/versionExpected:
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.2Approve, 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/coreand bundling: Larger actions use the toolkit (@actions/core,@actions/github) and bundle everything withnccoresbuildinto a single filedist/index.jsthat is committed to the repository. The runner does not runnpm install.- Docker instead of JS actions:
runs.using: dockerstarts 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.3and a mutablev1. 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.