workflows/README.md

workflows

Shared composite actions for the homelab CI/CD pipeline. (Composite actions, not reusable workflows: Forgejo LTS 11 does not support on: workflow_call.)

• node-checks — npm ci + lint + test (each --if-present)
• lint-checks — prettier + eslint + conventional-commit checks (each --if-present/config-gated); run after node-checks in the same job
• build-push — docker build + push to the Forgejo registry (git.lab.holtlabs.xyz), tags <short-sha> + latest
• gitops-bump — set the image tag in nholtware/gitops via kustomize edit set image; ArgoCD deploys from there

A consuming app's .forgejo/workflows/ci.yaml (see nholtware/demo-app):

on:
  push:
    branches: [main]
jobs:
  checks:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.lab.holtlabs.xyz/nholtware/workflows/node-checks@v1
      - uses: https://git.lab.holtlabs.xyz/nholtware/workflows/lint-checks@v1
  deploy:
    needs: checks
    runs-on: host
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.lab.holtlabs.xyz/nholtware/workflows/build-push@v1
        with:
          app-name: my-app
          registry-user: ${{ secrets.REGISTRY_USER }}
          registry-token: ${{ secrets.REGISTRY_TOKEN }}
      - uses: https://git.lab.holtlabs.xyz/nholtware/workflows/gitops-bump@v1
        with:
          app-name: my-app
          gitops-token: ${{ secrets.GITOPS_TOKEN }}

lint-checks expects the consuming repo to define its own tooling: a format:check npm script (e.g. prettier --check .) and a lint script (e.g. eslint .), plus their packages as devDependencies. The conventional-commit check only runs if a commitlint config (commitlint.config.* / .commitlintrc*) is present; add @commitlint/cli + @commitlint/config-conventional as devDependencies to use it.

Secrets are user-level Actions secrets on the repo owner: REGISTRY_USER, REGISTRY_TOKEN (write:package), GITOPS_TOKEN (write on the gitops repo). For a non-Node app, drop the checks job (or swap in your own) — deploy is language-agnostic.

Versioning

Consumers pin a moving major tag: uses: .../workflows/<action>@v1. Never reference @main (one bad push would break every repo at once).

• Compatible change (fix, new optional input): merge to main, then move the tag: git tag -f v1 && git push -f origin v1.
• Breaking change (renamed/required input, changed behaviour): tag v2, migrate consumers repo by repo, keep v1 where it was.