The Problem

Homelab operators need a single source that lists vetted open‑source applications and provides a reproducible way to generate a curated markdown table. Maintaining that list manually is error‑prone and makes it hard to keep badge counts (stars, language) up to date.

What This Does

The repository stores 35 YAML files under data/, each describing a category of homelab apps (e.g., data/ai.yaml, data/networking.yaml). A small Node.js script (script/index.js) reads those files, extracts key fields, and produces a markdown table similar to the one shown in README.md. Helper functions live in script/utils.js (toPascalCase, getRepoInfo, getBadge, getTitle) and script/yaml.js (getYAMLFiles). The CI workflow (.github/workflows/build.yaml) runs the script on every push, ensuring the public README stays in sync with the data files.

How It Is Wired

Execution starts at script/index.js (the only entry point). It calls two internal modules:

  1. script/utils.js – imported twice (instability = 1). Functions here perform the heavy lifting: list iterates over each YAML file returned by getYAMLFiles. For each app entry, getRepoInfo fetches GitHub metadata, getBadge builds the shield URLs, and getTitle formats the display name. * The call graph shows list → getBadge (twice) and list → getTitle, indicating that badge generation and title formatting dominate the runtime.
  1. script/yaml.js – provides getYAMLFiles, the sole consumer of the filesystem (the only external I/O). It scans data/ and returns an array of file paths.

script/utils.js has no outward dependencies beyond the standard library, so its functions are the widest blast radius; a change there affects every generated badge and title. No circular imports exist, and the module graph consists of four files with only two import edges, making the codebase easy to reason about.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/awesome-homelab.git
cd awesome-homelab

# Install dependencies with pnpm (lockfile present)
pnpm install

# Run the generator locally
node script/index.js

The script writes its output directly into README.md. No environment variables or external configuration files are required. To update the list, add or edit YAML files under data/ and push; the GitHub Actions workflow will regenerate the README automatically.

Real‑World Use

A homelab CI pipeline could schedule a nightly run of the GitHub Action to keep the public app list fresh. For example, a personal automation could fetch the generated README.md via the repository’s raw URL and embed the table in a self‑hosted documentation site, ensuring the site always reflects the latest curated apps without manual copy‑pasting.

Code Health & Issues

  • High – Pin third‑party GitHub Actions to a commit SHA – .github/workflows/build.yaml uses pnpm/action-setup@v4 and actions-js/push@master. Tags can be retagged, exposing the workflow to supply‑chain attacks. Replace each tag with a full SHA and let Dependabot update them.
  • Medium – Enable Dependabot or Renovate – only one manifest (package.json) exists; no update bot is configured. Add .github/dependabot.yml covering pnpm and github-actions.
  • Medium – Gate PRs with a dependency‑vulnerability scan – CI lacks a step that runs dependency-review-action or osv-scanner. Adding such a step will block known vulnerable packages from merging.
  • Medium – Review the install lifecycle script and disable scripts in CI – package.json contains a postinstall script that fetches a binary. This can be abused during CI builds. Either move the work to an explicit build step or run CI with ignore-scripts.
  • Low – Set timeout-minutes on workflow jobs – build.yaml omits a job timeout, risking runaway runs. Add a reasonable timeout (e.g., 15 min).
  • No test files – repository has zero tests, so code paths are unverified.
  • No LICENSE file – redistribution rights are unclear. Adding an MIT or Apache‑2.0 license would remove ambiguity.

The Bottom Line

The repo delivers a simple, well‑structured generator that keeps a homelab app catalog up to date with minimal friction. Its narrow module graph and single entry point make it easy to extend, but the lack of tests, a license, and several CI hardening gaps mean it should be hardened before being used in production‑grade automation. Suitable for personal or small‑team homelab documentation pipelines, provided the highlighted health issues are addressed.