Skip to content

Commit 522a03d

Browse files
karlspacekarlspace
committed
feat: Add Dockerfile validation workflow using Hadolint
- Introduced a new GitHub Actions workflow for validating Dockerfiles with Hadolint. - Added comprehensive configuration options for scanning directories, patterns, and thresholds. - Created documentation for the new workflow, including usage examples and input/output descriptions. - Implemented multiple example workflows for different use cases, including basic validation, multi-service projects, and strict production checks. - Included support for configuration files and combined validation with Docker Compose and Shell scripts.
1 parent c7d8836 commit 522a03d

File tree

8 files changed

+1101
-1
lines changed

8 files changed

+1101
-1
lines changed

‎.github/workflows/modules-validate-dockerfile.yml‎

Lines changed: 519 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/README.template.MD‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,10 @@ jobs:
171171
│ ├── esp32-build.yml # ESP32 microcontroller builds
172172
│ ├── stm32-build.yml # STM32 microcontroller builds
173173
│ ├── platformio-build.yml # PlatformIO cross-platform builds
174-
│ └── modules-*.yml # Module-specific workflows
174+
│ ├── modules-validate-dockerfile.yml # Dockerfile validation (Hadolint)
175+
│ ├── modules-validate-compose.yml # Docker Compose validation
176+
│ ├── modules-validate-shellscript.yml # Shell script validation (ShellCheck)
177+
│ └── modules-*.yml # Additional module workflows
175178
├── github/ # 🛠️ Repository Management Tools
176179
│ ├── branch-protect/ # Branch protection automation
177180
│ ├── claude-code/ # Claude Code documentation & tools
@@ -184,6 +187,7 @@ jobs:
184187
│ ├── coolify-deploy/ # Coolify deployment examples
185188
│ ├── docker/ # Docker build examples
186189
│ ├── docker-compose/ # Docker Compose examples
190+
│ ├── dockerfile-validation/ # Dockerfile linting examples
187191
│ ├── documentation/ # Documentation examples
188192
│ ├── dotnet-build/ # .NET project examples
189193
│ ├── dotnet-desktop-build/ # .NET desktop examples
@@ -214,6 +218,7 @@ jobs:
214218
│ │ ├── makefile-build.md # Makefile build system
215219
│ │ ├── meta-repository-sync.md # Meta repository sync
216220
│ │ ├── modules-validate-compose.md # Compose validation
221+
│ │ ├── modules-validate-dockerfile.md # Dockerfile validation (Hadolint)
217222
│ │ ├── modules-validate-shellscript.md # Shell validation
218223
│ │ ├── nodejs-build.md # Node.js build system
219224
│ │ ├── php-build.md # PHP build system
@@ -1083,6 +1088,12 @@ gh auth status --show-token
10831088
- [🔔 **Teams Notifications**](docs/workflows/teams-notifications.md) - Microsoft Teams integration
10841089
- [🏃 **Self-Hosted Runners**](docs/self-hosted-runners.md) - Self-hosted runner configuration guide
10851090

1091+
#### 🔍 Validation Modules
1092+
1093+
- [🐳 **Dockerfile Validation**](docs/workflows/modules-validate-dockerfile.md) - Dockerfile linting with Hadolint
1094+
- [📋 **Docker Compose Validation**](docs/workflows/modules-validate-compose.md) - Docker Compose validation
1095+
- [🐚 **Shell Script Validation**](docs/workflows/modules-validate-shellscript.md) - Shell script linting with ShellCheck
1096+
10861097
### 🔧 Actions Documentation
10871098

10881099
#### Build Actions
@@ -1142,6 +1153,7 @@ gh auth status --show-token
11421153

11431154
- [🐳 **Docker Examples**](github/workflows/examples/docker/) - Complete Docker workflow examples
11441155
- [🐳 **Docker Compose Examples**](github/workflows/examples/docker-compose/) - Docker Compose workflow examples
1156+
- [🐳 **Dockerfile Validation Examples**](github/workflows/examples/dockerfile-validation/) - Dockerfile linting examples
11451157
- [🐍 **Python Examples**](github/workflows/examples/python-build/) - Python build and test examples
11461158
- [🐍 **Python Release Examples**](github/workflows/examples/python-release/) - Python semantic release examples
11471159
- [⚡ **Zephyr Examples**](github/workflows/examples/zephyr-build/) - Zephyr RTOS project examples

‎docs/workflows/modules-validate-dockerfile.md‎

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
# 🐳 Dockerfile Validator Workflow
2+
3+
Professionelle Dockerfile-Validierung mit [Hadolint](https://github.com/hadolint/hadolint) - dem führenden Dockerfile-Linter, der Best Practices und Sicherheitsrichtlinien überprüft.
4+
5+
## Übersicht
6+
7+
Der `modules-validate-dockerfile` Workflow bietet:
8+
9+
- **Umfassende Linting-Analyse** - Überprüft Dockerfiles auf Best Practices
10+
- **Sicherheits-Checks** - Erkennt potenzielle Sicherheitsprobleme
11+
- **Flexible Konfiguration** - Anpassbare Regeln und Schwellenwerte
12+
- **Multi-Dockerfile-Support** - Scannt mehrere Dockerfiles parallel
13+
- **Detaillierte Reports** - GitHub Summary mit allen Findings
14+
15+
## Schnellstart
16+
17+
### Minimale Konfiguration
18+
19+
```yaml
20+
name: 🐳 Validate Dockerfiles
21+
22+
on: [push, pull_request]
23+
24+
jobs:
25+
validate:
26+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
27+
```
28+
29+
### Empfohlene Konfiguration
30+
31+
```yaml
32+
name: 🐳 Dockerfile Validation
33+
34+
on:
35+
push:
36+
paths:
37+
- '**/Dockerfile*'
38+
- '**/*.Dockerfile'
39+
pull_request:
40+
paths:
41+
- '**/Dockerfile*'
42+
- '**/*.Dockerfile'
43+
44+
jobs:
45+
hadolint:
46+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
47+
with:
48+
failure-threshold: 'warning'
49+
trusted-registries: '["docker.io", "ghcr.io"]'
50+
ignore-rules: '["DL3008"]'
51+
```
52+
53+
## Inputs
54+
55+
| Input | Typ | Default | Beschreibung |
56+
|-------|-----|---------|--------------|
57+
| `scan-directory` | string | `.` | Verzeichnis zum Scannen |
58+
| `scan-paths` | string (JSON) | `''` | Spezifische Pfade `["docker/", "services/"]` |
59+
| `dockerfile-patterns` | string (JSON) | `["Dockerfile", "Dockerfile.*", "*.Dockerfile"]` | Dateinamenmuster |
60+
| `recursive` | boolean | `true` | Rekursive Suche |
61+
| `failure-threshold` | string | `warning` | Schwellenwert: `error`, `warning`, `info`, `style`, `ignore` |
62+
| `ignore-rules` | string (JSON) | `''` | Zu ignorierende Regeln `["DL3008", "DL3013"]` |
63+
| `trusted-registries` | string (JSON) | `''` | Vertrauenswürdige Registries `["docker.io", "ghcr.io"]` |
64+
| `config-file` | string | `''` | Pfad zur `.hadolint.yaml` |
65+
| `format` | string | `tty` | Ausgabeformat |
66+
| `fail-on-findings` | boolean | `true` | Bei Findings fehlschlagen |
67+
| `override-error` | string (JSON) | `''` | Regeln als Error behandeln |
68+
| `override-warning` | string (JSON) | `''` | Regeln als Warning behandeln |
69+
| `override-info` | string (JSON) | `''` | Regeln als Info behandeln |
70+
| `override-style` | string (JSON) | `''` | Regeln als Style behandeln |
71+
| `runs-on` | string | `ubuntu-latest` | Runner-Konfiguration |
72+
73+
## Outputs
74+
75+
| Output | Beschreibung |
76+
|--------|--------------|
77+
| `passed` | `true` wenn alle Dockerfiles die Validierung bestanden |
78+
| `files-checked` | Anzahl der geprüften Dockerfiles |
79+
| `issues-found` | Gesamtanzahl der gefundenen Issues |
80+
| `error-count` | Anzahl der Errors |
81+
| `warning-count` | Anzahl der Warnings |
82+
| `info-count` | Anzahl der Info-Meldungen |
83+
| `style-count` | Anzahl der Style-Issues |
84+
85+
## Failure Threshold
86+
87+
Der `failure-threshold` bestimmt, ab welcher Severity der Workflow fehlschlägt:
88+
89+
| Threshold | Fehler bei | Use Case |
90+
|-----------|------------|----------|
91+
| `error` | Nur bei Errors | Produktions-Builds, nur kritische Issues |
92+
| `warning` | Errors + Warnings | **Empfohlen** - Standardmäßige Qualitätsprüfung |
93+
| `info` | Errors + Warnings + Info | Strenge Qualitätskontrolle |
94+
| `style` | Alle Issues | Maximale Codequalität |
95+
| `ignore` | Nie | Nur für Reports, kein Fail |
96+
97+
## Beispiele
98+
99+
### Multi-Service Docker-Projekt
100+
101+
```yaml
102+
name: 🐳 Docker Lint
103+
104+
on:
105+
push:
106+
paths:
107+
- 'services/**/Dockerfile*'
108+
- 'docker/**'
109+
110+
jobs:
111+
lint:
112+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
113+
with:
114+
scan-paths: '["services/", "docker/"]'
115+
failure-threshold: 'warning'
116+
trusted-registries: '["ghcr.io", "docker.io", "mcr.microsoft.com"]'
117+
```
118+
119+
### Mit Konfigurationsdatei
120+
121+
```yaml
122+
name: 🐳 Hadolint Check
123+
124+
on: [push, pull_request]
125+
126+
jobs:
127+
validate:
128+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
129+
with:
130+
config-file: '.hadolint.yaml'
131+
fail-on-findings: true
132+
```
133+
134+
**.hadolint.yaml:**
135+
136+
```yaml
137+
ignored:
138+
- DL3008 # Pin versions in apt-get
139+
- DL3013 # Pin versions in pip
140+
141+
trustedRegistries:
142+
- docker.io
143+
- ghcr.io
144+
- mcr.microsoft.com
145+
146+
override:
147+
error:
148+
- DL3001 # WORKDIR statt cd
149+
- DL3002 # Nicht zu root wechseln
150+
warning:
151+
- DL3042 # Cache verwenden
152+
```
153+
154+
### Strenge Production Pipeline
155+
156+
```yaml
157+
name: 🐳 Production Dockerfile Validation
158+
159+
on:
160+
pull_request:
161+
branches: [main]
162+
paths:
163+
- '**/Dockerfile*'
164+
165+
jobs:
166+
strict-lint:
167+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
168+
with:
169+
failure-threshold: 'info'
170+
ignore-rules: '[]' # Keine Ausnahmen
171+
override-error: '["DL3007", "DL3006"]' # latest Tag als Error
172+
trusted-registries: '["ghcr.io/company"]' # Nur Company Registry
173+
```
174+
175+
### Self-Hosted Runner
176+
177+
```yaml
178+
jobs:
179+
validate:
180+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
181+
with:
182+
runs-on: '["self-hosted", "linux", "docker"]'
183+
failure-threshold: 'warning'
184+
```
185+
186+
### Nur Reporting (kein Fail)
187+
188+
```yaml
189+
jobs:
190+
report:
191+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
192+
with:
193+
failure-threshold: 'ignore'
194+
fail-on-findings: false
195+
```
196+
197+
## Wichtige Hadolint-Regeln
198+
199+
### Sicherheit
200+
201+
| Regel | Beschreibung | Empfehlung |
202+
|-------|--------------|------------|
203+
| DL3002 | Wechsel zu root USER | Vermeiden - Security Risk |
204+
| DL3004 | sudo in RUN | Vermeiden - nicht notwendig in Docker |
205+
| DL3006 | Image ohne Tag | Immer Version taggen |
206+
| DL3007 | `latest` Tag verwendet | Spezifische Version nutzen |
207+
208+
### Best Practices
209+
210+
| Regel | Beschreibung | Empfehlung |
211+
|-------|--------------|------------|
212+
| DL3000 | Absoluter WORKDIR-Pfad | `/app` statt `app` |
213+
| DL3001 | `cd` in RUN | WORKDIR verwenden |
214+
| DL3003 | `cd` und Befehl trennen | WORKDIR + RUN |
215+
| DL3025 | CMD Format | JSON-Array: `["cmd", "arg"]` |
216+
217+
### Paket-Management
218+
219+
| Regel | Beschreibung | Empfehlung |
220+
|-------|--------------|------------|
221+
| DL3008 | apt-get ohne Version | `package=version` pinnen |
222+
| DL3013 | pip ohne Version | `package==version` pinnen |
223+
| DL3018 | apk ohne Version | `package=version` pinnen |
224+
| DL3028 | gem ohne Version | `gem install pkg -v version` |
225+
226+
## Workflow mit anderen Validatoren kombinieren
227+
228+
```yaml
229+
name: 🔍 Full Docker Validation
230+
231+
on: [push, pull_request]
232+
233+
jobs:
234+
# Dockerfile Linting
235+
hadolint:
236+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
237+
with:
238+
failure-threshold: 'warning'
239+
240+
# Docker Compose Validation
241+
compose:
242+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-compose.yml@main
243+
with:
244+
compose-file: 'docker-compose.yml'
245+
246+
# Shell Script Validation (für Entrypoints)
247+
shellcheck:
248+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-shellscript.yml@main
249+
with:
250+
scan-paths: '["scripts/", "docker/"]'
251+
252+
# Abschließender Check
253+
summary:
254+
needs: [hadolint, compose, shellcheck]
255+
runs-on: ubuntu-latest
256+
steps:
257+
- name: 📊 Validation Summary
258+
run: |
259+
echo "### Docker Validation Summary" >> $GITHUB_STEP_SUMMARY
260+
echo "- Hadolint: ${{ needs.hadolint.outputs.passed && '✅' || '❌' }}" >> $GITHUB_STEP_SUMMARY
261+
echo "- Compose: ${{ needs.compose.outputs.valid && '✅' || '❌' }}" >> $GITHUB_STEP_SUMMARY
262+
echo "- ShellCheck: ${{ needs.shellcheck.outputs.passed && '✅' || '❌' }}" >> $GITHUB_STEP_SUMMARY
263+
```
264+
265+
## Empfohlene .hadolint.yaml
266+
267+
```yaml
268+
# .hadolint.yaml - Empfohlene Konfiguration
269+
---
270+
# Regeln ignorieren (mit Begründung)
271+
ignored:
272+
# Version-Pinning oft nicht praktikabel für Base-Images
273+
# - DL3008
274+
275+
# Vertrauenswürdige Registries
276+
trustedRegistries:
277+
- docker.io
278+
- ghcr.io
279+
- mcr.microsoft.com
280+
- gcr.io
281+
- quay.io
282+
283+
# Severity-Overrides
284+
override:
285+
# Kritische Sicherheitsregeln als Error
286+
error:
287+
- DL3002 # Nicht zu root wechseln
288+
- DL3004 # Kein sudo verwenden
289+
290+
# Wichtige Best Practices als Warning
291+
warning:
292+
- DL3007 # latest Tag vermeiden
293+
- DL3025 # JSON CMD Format
294+
295+
# Labels die in Dockerfiles sein sollten (optional)
296+
label-schema:
297+
author: text
298+
version: semver
299+
```
300+
301+
## Ressourcen
302+
303+
- [Hadolint GitHub](https://github.com/hadolint/hadolint)
304+
- [Hadolint Rules Reference](https://github.com/hadolint/hadolint#rules)
305+
- [Dockerfile Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
306+
- [Docker Security Best Practices](https://snyk.io/blog/10-docker-image-security-best-practices/)

‎github/workflows/examples/dockerfile-validation/basic-validation.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Einfache Dockerfile-Validierung
2+
# Scannt alle Dockerfiles im Repository mit Standard-Einstellungen
3+
4+
name: 🐳 Dockerfile Lint
5+
6+
on:
7+
push:
8+
paths:
9+
- '**/Dockerfile*'
10+
- '**/*.Dockerfile'
11+
pull_request:
12+
paths:
13+
- '**/Dockerfile*'
14+
- '**/*.Dockerfile'
15+
16+
jobs:
17+
hadolint:
18+
uses: bauer-group/automation-templates/.github/workflows/modules-validate-dockerfile.yml@main
19+
with:
20+
failure-threshold: 'warning'

0 commit comments

Comments
 (0)