Contents of the docs
github-workflows · Docs
Node.js Docker CI/CD
Reusable workflow for test, build, release, multi-arch Docker image in GHCR, deployment via Dockhand and notification to Home Assistant.
node-docker.yml is the
complete pipeline for a Node.js project that runs as a Docker container. It consists of three jobs.
Flow
- publish
- Checks out the repository with full history and sets up Node.js with npm cache.
- Runs
npm ci,npm run test --if-presentandnpm run build --if-present. - On
mainormaster:npm run semantic-release --if-present. - If the current commit carries the tag
v<version>frompackage.json, i.e. this run created a release, it builds an image forlinux/amd64andlinux/arm64from theDockerfileand pushes it toghcr.io/<owner>/<repo>with the tags<major>,<major>.<minor>,<version>andlatest.
- deploy – only when an image was published and
deployistrue: updates the container in the given Dockhand environment to the newlatestimage, see Dockhand Update. - notify – always runs and reports the result to Home Assistant, see Home Assistant Notification. A skipped deployment counts as success.
Requirements in the project
package.jsonwithversionand apackage-lock.json- an npm script
semantic-releasewith its configuration if releases should be created - a
Dockerfilein the root folder - optionally the npm scripts
testandbuild
Call
name: CI/CD
on:
push:
branches: [ main ]
workflow_dispatch:
permissions:
contents: write
packages: write
issues: write
pull-requests: write
jobs:
pipeline:
uses: DasRed/github-workflows/.github/workflows/node-docker.yml@v1
secrets:
dockhand-host: ${{ secrets.DOCKHAND_HOST }}
dockhand-token: ${{ secrets.DOCKHAND_TOKEN }}
homeassistant-webhook-url: ${{ secrets.HOMEASSISTANT_WEBHOOK_URL }}
with:
environment: production
container-name: my-containerImportant
The permissions in the calling workflow are required. They limit what the GITHUB_TOKEN may do inside the
reusable workflow: write access for tags and releases, packages for the image, issues and pull requests for the
comments of semantic-release.
Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
environment |
string | yes | Name of the Dockhand environment to deploy to | |
container-name |
string | no | repository name | Name of the container to update |
node-version |
string | no | 26 |
Node.js version for install, test and build |
deploy |
boolean | no | true |
false only publishes the image |
Secrets
| Name | Required | Description |
|---|---|---|
dockhand-host |
yes | Base URL of the Dockhand server, e.g. https://dockhand.example.com |
dockhand-token |
yes | Dockhand API token |
homeassistant-webhook-url |
yes | Full URL of the Home Assistant webhook |
Outputs
| Name | Description |
|---|---|
released |
true if the run created a release and published the image, otherwise false |
version |
Version of the release from package.json, empty without a release |
image |
Image name without tag, e.g. ghcr.io/owner/repo |
Further jobs can react to a release with them, e.g. MCP Registry Publish.
Good to know
- No release, no image. Commits without
feat:,fix:orperf:create no release, hence no image and no deployment. The run is still green. environmentand all secrets are required, even withdeploy: false. The Home Assistant notification cannot be switched off.- Runner: all jobs run on
ubuntu-26.04. - Cache: the Docker build uses the GitHub Actions cache (
type=gha), which speeds up later builds considerably.