---
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"
```
