docs: document dummy-credential convention; annotate examples

Add CONTRIBUTING.md explaining the linting setup and how to mark the
repo's intentional dummy credentials so gitleaks does not flag them:
inline `# gitleaks:allow` for lint-clean, comment-capable files, and a
.gitleaksignore baseline otherwise.

Annotate the dummy credentials in four already-lint-clean example files
inline, as the preferred convention going forward.

- DIUN/docker-compose.yaml
- Headscale/Tailscale-Client/docker-compose,yaml
- Homepage/Homepage/services.yaml
- Kubernetes/Traefik-PiHole/Helm/Traefik/Dashboard/secret-dashboard.yaml

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+Thanks for contributing to JimsGarage! This guide covers the automated checks
+that run on pull requests and — importantly for this repo — how to handle the
+**dummy credentials** that many of these tutorials intentionally ship.
+
+## Linting
+
+A `pre-commit` configuration (`.pre-commit-config.yaml`) and a GitHub Actions
+workflow (`.github/workflows/lint.yml`) run a set of checks. CI lints **only the
+files changed in your PR**, so you are not responsible for pre-existing issues in
+files you do not touch.
+
+To run the checks locally before pushing:
+
+```bash
+pip install pre-commit
+pre-commit install            # optional: run automatically on every commit
+pre-commit run --all-files    # or scope to changed files (CI behavior)
+```
+
+The hooks include general hygiene (trailing whitespace, end-of-file newline),
+`yamllint`, `shellcheck`, `actionlint`, and `gitleaks` (secret scanning).
+
+## Credentials and secrets
+
+**Never commit a real credential.** If you accidentally commit one, treat it as
+compromised: rotate it, then remove it from history.
+
+Many tutorials here include **throwaway / dummy credentials** so a config works
+out of the box when copied. That is fine — but because they live next to real
+config, the `gitleaks` scanner cannot tell a deliberate dummy from a genuine
+leak. You therefore need to mark intentional dummies explicitly. There are two
+ways to do this; prefer the first.
+
+### 1. Inline annotation (preferred)
+
+For a dummy value in a **comment-capable file that is already lint-clean**, add a
+trailing `# gitleaks:allow` on the offending line:
+
+```yaml
+environment:
+  - "ADMIN_TOKEN=not-a-real-token-1234567890"  # gitleaks:allow
+```
+
+This is self-documenting at the point of use and is the convention for any
+**new** dummy credential you add.
+
+### 2. Baseline in `.gitleaksignore`
+
+Some findings cannot or should not be annotated inline. For these, add the
+finding's fingerprint to `.gitleaksignore`. Use this when the file is:
+
+- **JSON** — it has no comment syntax (e.g. `Netbird/management.json`).
+- A **multi-line PEM private-key block** — an inline marker is unreliable across
+  the block (e.g. `Authelia/Authelia/configuration.yml`).
+- **Burdened with pre-existing lint debt** — editing it would pull the whole file
+  into the changed-files lint scope and fail unrelated `yamllint`/hygiene checks.
+
+To get a fingerprint, scan and copy the `Fingerprint` field for the finding:
+
+```bash
+gitleaks dir . --report-format json --report-path /tmp/gitleaks.json
+# copy the "Fingerprint" value into .gitleaksignore, with a brief comment
+```
+
+### Allowlisted paths
+
+`.gitleaks.toml` already allowlists conventional placeholder locations — tracked
+`.env` files and `*example*` / `*sample*` files — since those are dummy by
+convention in this repo. Secrets placed there are not scanned, so do not rely on
+them to hold anything real.

DIUN/docker-compose.yaml

@@ -19,7 +19,7 @@ services:
       - "DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT=true"
 
       - "DIUN_NOTIF_GOTIFY_ENDPOINT=https://gotify.jimsgarage.co.uk"
-      - "DIUN_NOTIF_GOTIFY_TOKEN=AYgfdfQaRk3Pb1x" # get your token from Gotify UI
+      - "DIUN_NOTIF_GOTIFY_TOKEN=AYgfdfQaRk3Pb1x" # get your token from Gotify UI  # gitleaks:allow
       - "DIUN_NOTIF_GOTIFY_PRIORITY=1"
       - "DIUN_NOTIF_GOTIFY_TIMEOUT=10s"
 

Headscale/Tailscale-Client/docker-compose.yaml

@@ -14,5 +14,5 @@ services:
       - TS_STATE_DIR=/var/lib/tailscale
       - TS_EXTRA_ARGS=--login-server=https://headscale.jimsgarage.co.uk --advertise-exit-node --advertise-routes=192.168.0.0/16 --accept-dns=true
       - TS_NO_LOGS_NO_SUPPORT=true
-     # - TS_AUTHKEY=e6f46b99f2ddsfsf3easdf125590e415db007 # generate this key inside your headscale server container  
+     # - TS_AUTHKEY=e6f46b99f2ddsfsf3easdf125590e415db007 # generate this key inside your headscale server container  # gitleaks:allow
     restart: unless-stopped

Homepage/Homepage/services.yaml

@@ -17,7 +17,7 @@
           type: traefik
           url: https://traefik.jimsgarage.co.uk
           username: admin
-          password: gT8ni3iX6QkKreWfAdYKe4xqVsaMRUQ4GG7xn59Q
+          password: gT8ni3iX6QkKreWfAdYKe4xqVsaMRUQ4GG7xn59Q  # gitleaks:allow
 
     - PiHole:
         icon: pi-hole.png
@@ -28,7 +28,7 @@
         widget:
           type: pihole
           url: http://192.168.8.2
-          key: 73T8oBs9MFKLVAC3mAs2KQbWSsqA7oe2PN9r9H4TQWg2TXNAdq4ZPzvy8oEv
+          key: 73T8oBs9MFKLVAC3mAs2KQbWSsqA7oe2PN9r9H4TQWg2TXNAdq4ZPzvy8oEv  # gitleaks:allow
 
 - My Second Group:
     - My Second Service:

Kubernetes/Traefik-PiHole/Helm/Traefik/Dashboard/secret-dashboard.yaml

@@ -1,6 +1,6 @@
 ---
 apiVersion: v1
-kind: Secret
+kind: Secret  # gitleaks:allow
 metadata:
   name: traefik-dashboard-auth
   namespace: traefik