# 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
  (`192.168.1.230:3000`), 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):

```yaml
on:
  push:
    branches: [main]
jobs:
  checks:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - uses: http://192.168.1.230:3000/nholtware/workflows/node-checks@v1
      - uses: http://192.168.1.230:3000/nholtware/workflows/lint-checks@v1
  deploy:
    needs: checks
    runs-on: host
    steps:
      - uses: actions/checkout@v4
      - uses: http://192.168.1.230:3000/nholtware/workflows/build-push@v1
        with:
          app-name: my-app
          registry-user: ${{ secrets.REGISTRY_USER }}
          registry-token: ${{ secrets.REGISTRY_TOKEN }}
      - uses: http://192.168.1.230:3000/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.