From d8ec53c03570e6f9ede8bf4bd889c080e36e3ad1 Mon Sep 17 00:00:00 2001 From: Administrator Date: Wed, 6 May 2026 21:12:33 +0000 Subject: [PATCH] docs: create Netgrimoire/Gremlin-Grimoire/Gremlin_Directives --- .../Gremlin-Grimoire/Gremlin_Directives.md | 283 ++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 Netgrimoire/Gremlin-Grimoire/Gremlin_Directives.md diff --git a/Netgrimoire/Gremlin-Grimoire/Gremlin_Directives.md b/Netgrimoire/Gremlin-Grimoire/Gremlin_Directives.md new file mode 100644 index 0000000..0860ee7 --- /dev/null +++ b/Netgrimoire/Gremlin-Grimoire/Gremlin_Directives.md @@ -0,0 +1,283 @@ +--- +title: Gremlin CI/CD Directives +description: Gremlin Cheatsheet +published: true +date: 2026-05-06T21:12:26.442Z +tags: +editor: markdown +dateCreated: 2026-05-06T21:12:26.442Z +--- + +# Gremlin Directives Cheatsheet +description: Quick reference for all Gremlin CI/CD directive labels and commit directives. +published: true +date: 2026-05-06 +tags: gremlin, cicd, directives, reference, netgrimoire +editor: markdown +dateCreated: 2026-05-06 +--- + +# Gremlin Directives Cheatsheet + +> **NetGrimoire Quick Reference** +> All Gremlin directive labels and commit directives in one place. + +--- + +## Directive Scopes + +| Scope | Where to put it | Effect | +|---|---|---| +| **File-level** | Any service's `labels:` block | Applies to entire stack file | +| **Per-service** | The specific service's `labels:` block | Applies only to that service | +| **Commit** | `[gremlin: key=value]` in commit message | Overrides all file directives | + +**Priority:** commit directives > file directives > `gremlin/config.yaml` defaults + +--- + +## File-Level Directives + +Place on any service — applies to the whole file. + +| Directive | Values | Default | Effect | +|---|---|---|---| +| `gremlin.enable` | `"true"` / `"false"` | `true` | Skip file entirely when false | +| `gremlin.deploy` | `"true"` / `"false"` | `true` | Skip deploy step when false | +| `gremlin.autofix` | `"true"` / `"false"` | `true` | Disable auto-fix when false | +| `gremlin.autofix.mode` | `"override"` | _(unset)_ | Write fixes to override file, never touch original | +| `gremlin.checks` | `"all"` | `"all"` | Which checks to run | +| `gremlin.checks.skip` | comma-separated IDs | _(none)_ | Skip specific checkers | +| `gremlin.version` | `"2026-04-1"` | _(stamped)_ | Pipeline version stamp | +| `gremlin.context` | any string | _(none)_ | Context passed to Ollama to prevent false positives | +| `gremlin.notify` | `"true"` / `"false"` | `true` | Disable ntfy notifications | +| `gremlin.notify.level` | `"all"` / `"errors"` | `"all"` | Notification verbosity | + +--- + +## Per-Service Directives + +Must be on the specific service they apply to — not file-wide. + +### Identity + +| Directive | Values | Effect | +|---|---|---| +| `gremlin.uid.exempt` | `"true"` | Skip PUID/PGID check for this service | +| `gremlin.uid.reason` | any string | Document why uid is exempt (required with uid.exempt) | + +**Use for:** Postgres, Redis, Authentik, and any image that manages its own users. + +```yaml +labels: + gremlin.uid.exempt: "true" + gremlin.uid.reason: "Postgres requires UID 999 — PUID/PGID not supported" +``` + +### Placement + +| Directive | Values | Effect | +|---|---|---| +| `gremlin.arm.allow` | `"true"` | Skip ARM exclusion requirement for this service | + +**Use for:** Pi-specific services, multi-arch images. + +```yaml +labels: + gremlin.arm.allow: "true" +``` + +### Caddy + +| Directive | Values | Effect | +|---|---|---| +| `gremlin.caddy.skip` | `"true"` | Skip all Caddy checks for this service | +| `gremlin.authentik.skip` | `"true"` | Skip `caddy.import_2: authentik` requirement only | +| `gremlin.caddy.reverse_proxy.skip` | `"true"` | Skip `caddy.reverse_proxy` check only | +| `gremlin.port` | port number | Declare internal port when no `ports:` mapping exists | + +**Use caddy.skip for:** internal-only services, services proxied via static Caddyfile (e.g. Kopia h2c). + +```yaml +labels: + gremlin.caddy.skip: "true" + gremlin.context: "Kopia uses h2c — configured in static Caddyfile" +``` + +**Use authentik.skip for:** services with their own auth (Authelia, public endpoints). + +```yaml +labels: + caddy: myservice.wasted-bandwidth.net + caddy.import_1: crowdsec + gremlin.authentik.skip: "true" + # caddy.import_2: authentik is NOT required +``` + +**Use gremlin.port for:** services with no published port mapping. + +```yaml +environment: + PORT: "8080" +labels: + gremlin.port: "8080" + caddy: myservice.netgrimoire.com + caddy.reverse_proxy: myservice:8080 +``` + +### Homepage + +| Directive | Values | Effect | +|---|---|---| +| `gremlin.homepage.skip` | `"true"` | Skip homepage label checks for this service | + +**Use for:** internal agents, background workers, database sidecars. + +### Monitor + +| Directive | Values | Effect | +|---|---|---| +| `gremlin.monitor.skip` | `"true"` | Skip monitor label checks for this service | + +**Use for:** databases (no HTTP endpoint), internal-only services. + +### Network + +| Directive | Values | Effect | +|---|---|---| +| `gremlin.network.skip` | `"true"` | Skip netgrimoire network check for this service | + +### Diun + +| Directive | Values | Effect | +|---|---|---| +| `gremlin.diun.skip` | `"true"` | Skip diun.enable check for this service | + +--- + +## Commit Directives + +Append `[gremlin: key=value]` to any commit message. Overrides file and config directives. + +```bash +git commit -m "your message [gremlin: key=value key2=value2]" +``` + +| Directive | Values | Effect | +|---|---|---| +| `deploy` | `true` / `false` | Force enable or disable deploy | +| `autofix` | `true` / `false` | Force enable or disable auto-fix | +| `checks.skip` | comma-separated checker IDs | Skip specific checkers | +| `notify` | `true` / `false` | Enable or disable ntfy | +| `notify.level` | `all` / `errors` | Notification verbosity | +| `enable` | `true` / `false` | Enable or disable pipeline entirely | + +### Checker IDs + +**Swarm:** `syntax` `identity` `network` `placement` `caddy` `homepage` `monitor` `legacy-labels` `version` `diun` + +**Compose:** `compose-syntax` `compose-identity` `compose-network` `compose-caddy` `compose-homepage` `compose-monitor` `compose-diun` `compose-version` + +--- + +## Common Directive Combinations + +### Internal-only service (no web UI) + +```yaml +labels: + gremlin.version: "2026-04-1" + gremlin.caddy.skip: "true" + gremlin.homepage.skip: "true" + gremlin.monitor.skip: "true" + diun.enable: "true" +``` + +### Database sidecar + +```yaml +labels: + gremlin.version: "2026-04-1" + gremlin.uid.exempt: "true" + gremlin.uid.reason: "Postgres manages its own UID" + gremlin.caddy.skip: "true" + gremlin.homepage.skip: "true" + gremlin.monitor.skip: "true" + diun.enable: "true" +``` + +### ARM / Pi service + +```yaml +labels: + gremlin.version: "2026-04-1" + gremlin.arm.allow: "true" + # ... other labels +``` + +### Service behind Authelia instead of Authentik + +```yaml +labels: + caddy: myservice.wasted-bandwidth.net + caddy.import_1: crowdsec + caddy.import_2: authelia # Note: authelia not authentik + gremlin.authentik.skip: "true" + caddy.reverse_proxy: myservice:8080 +``` + +### Vendor file — never modify original + +```yaml +labels: + gremlin.version: "2026-04-1" + gremlin.autofix.mode: "override" + # all other labels go in override file automatically +``` + +### Force redeploy without changing file + +```bash +git commit --allow-empty -m "redeploy [gremlin: deploy=true checks.skip=all autofix=false]" +git push +``` + +### Skip all checks for known-good file + +```bash +git commit -m "deploy vendor compose [gremlin: checks.skip=all autofix=false deploy=true]" +``` + +--- + +## Standard Label Block Templates + +### Full Swarm service (web-facing) + +```yaml +labels: + gremlin.version: "2026-04-1" + caddy: myservice.netgrimoire.com + caddy.reverse_proxy: myservice:8080 + caddy.import_1: crowdsec + caddy.import_2: authentik + homepage.group: "My Group" + homepage.name: "My Service" + homepage.icon: "myservice.png" + homepage.href: "https://myservice.netgrimoire.com" + homepage.description: "Brief description" + monitor.name: "My Service" + monitor.url: "http://myservice:8080" + diun.enable: "true" +``` + +### Minimal Swarm service (internal) + +```yaml +labels: + gremlin.version: "2026-04-1" + gremlin.caddy.skip: "true" + gremlin.homepage.skip: "true" + gremlin.monitor.skip: "true" + diun.enable: "true" +```