stack-validator_skill

Overview

This skill validates GitLab stack projects before deployment to ensure architecture patterns, secrets handling, environment configuration, and Docker best practices are followed. It detects and reports security and structural issues and produces a prioritized validation report. The skill integrates findings from Docker validation and recommends companion skills for remediation.

How this skill works

The validator inspects the repository for key indicators (docker-compose.yml, ./config, ./secrets, .env, ./_temporary) and runs a phased workflow: pre-flight checks, directory and permissions audits, .env synchronization, Docker compose and Dockerfile checks, secrets validation, config syntax checks, script reviews, temporary file audits, and ownership scans. It aggregates findings into a severity-ranked report and can export results as formatted text or JSON. When available, it respects a .stack-validator.yml for custom rules and can operate in strict, standard, or permissive modes.

When to use it

• Before deploying a stack to catch configuration or security issues early
• When auditing a project for best-practice compliance and secrets management
• When preparing a merge or release to ensure .env and .env.example match
• When onboarding or reviewing a GitLab stack repository
• After structural changes to verify directory, permission, and ownership correctness

Best practices

• Keep secrets out of .env; store them in ./secrets and reference via Docker secrets
• Maintain a .env.example that matches .env exactly to avoid missing variables
• Ensure ./secrets and ./_temporary are in .gitignore and have restrictive permissions
• Avoid root-owned files; ensure files are owned by the application or docker user
• Prefer native Docker secrets over entrypoint scripts for secret handling

Example use cases

• Run a pre-deployment check to ensure no secrets are leaked in config or .env
• Audit a CI pipeline repository to verify docker-compose.yml follows modern spec
• Validate a colleague's stack before merge to prevent permission or ownership regressions
• Generate a JSON validation report to feed into automated CI gating
• Identify and prioritize remediation steps for a legacy stack with mixed ownership