docs: create Netgrimoire/Gremlin-Grimoire/Gremlin_Directives
This commit is contained in:
Administrator
John Smith
parent
35a791f69d
commit
d8ec53c035
1 changed files with 283 additions and 0 deletions
283
Netgrimoire/Gremlin-Grimoire/Gremlin_Directives.md
Normal file
283
Netgrimoire/Gremlin-Grimoire/Gremlin_Directives.md
Normal file
|
|
@ -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"
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue