Ansible Generator

Trigger Phrases

Use this skill when the request is to generate or scaffold Ansible content, for example:

• "Create a playbook to deploy nginx with TLS."
• "Generate an Ansible role for PostgreSQL backups."
• "Write inventory files for prod and staging."
• "Build reusable Ansible tasks for user provisioning."
• "Initialize an Ansible project with ansible.cfg and requirements.yml."
• "Give me a quick Ansible snippet to install Docker."

Do not use this skill as the primary workflow when the request is validation/debug-only (syntax errors, lint failures, Molecule/test failures). Use ansible-validator for those cases.

Deterministic Execution Flow

Run these stages in order. Do not skip a stage unless the Validation Exceptions Matrix explicitly allows it.

Stage 0: Classify Request Mode

Determine one mode first:

Stage 1: Collect Minimum Inputs

If details are missing, ask briefly. If the user does not provide them, proceed with safe defaults and state assumptions.

Stage 2: Reference Extraction Checklist

Before drafting content, extract the following from local references/templates.

Required references

• references/best-practices.md
  • Extract: FQCN requirements, idempotency rules, naming, security expectations.
• references/module-patterns.md
  • Extract: correct module/parameter patterns for the exact task type.

Required templates by output type

• Playbook: assets/templates/playbook/basic_playbook.yml
• Role: assets/templates/role/ (including meta/argument_specs.yml and molecule/default/ for test scaffolding)
• Inventory (INI): assets/templates/inventory/hosts
• Inventory (YAML): assets/templates/inventory/hosts.yml
• Project config: assets/templates/project/ansible.cfg, assets/templates/project/requirements.yml, assets/templates/project/.ansible-lint

Extraction checks

• Identify every [PLACEHOLDER] that must be replaced.
• Decide module selection priority (ansible.builtin.* first).
• Capture at least one OS-appropriate package pattern when OS-specific behavior is needed.
• Capture required prerequisites (collections, binaries, target assumptions).

Stage 3: Generate

Apply these generation standards:

1. Use FQCN module names (ansible.builtin.* first choice).
2. Keep tasks idempotent (state, creates/removes, changed_when when needed).
3. Use descriptive verb-first task names.
4. Use true/false booleans (not yes/no).
5. Add no_log: true for sensitive values.
6. Replace all placeholders before presenting output.
7. Prefer ansible.builtin.dnf for RHEL 8+/CentOS 8+ (legacy yum only for older systems).

Stage 4: Validate (Default) or Apply Exception (Fallback)

Use the matrix below to keep validation deterministic and non-blocking.

Validation Exceptions Matrix

Resource Generation Guidance

Playbooks

• Use assets/templates/playbook/basic_playbook.yml as structure.
• Include: header comments, pre_tasks/tasks/post_tasks as needed, handlers, tags.
• Add health checks when service deployment/configuration is involved.

Roles

• Build from assets/templates/role/ structure.
• Keep defaults in defaults/main.yml; keep higher-priority role vars in vars/main.yml.
• Include OS-specific vars (vars/Debian.yml, vars/RedHat.yml) when relevant.
• Add meta/argument_specs.yml for variable validation.
• Include molecule/default/ scaffold (from assets/templates/role/molecule/) for production-ready roles.

Task Files

• Keep scope narrow and reusable.
• Document required input variables in comments.
• Use conditionals for environment/OS-sensitive operations.

Inventory

• Build logical host groups and optional group hierarchies.
• Use variable layering intentionally: group_vars/all.yml -> group -> host.
• Default to INI format (hosts) for simple topologies; use YAML format (hosts.yml) when the user requests it or when the hierarchy is complex.

Project Configuration

• Provide baseline ansible.cfg, requirements.yml, and .ansible-lint.
• Keep defaults practical and editable.

Custom Modules and Collections

When the request depends on non-builtin modules/collections:

1. Identify collection + module and required version sensitivity.
2. Check local references/module-patterns.md first.
3. If still unresolved and network/tools are available, query Context7:
   • mcp__context7__resolve-library-id
   • mcp__context7__query-docs
4. If Context7 is unavailable, use official Ansible docs / Ansible Galaxy pages.
5. If external lookup is unavailable, provide a builtin fallback approach and state the limitation.

Always include collection installation guidance when collection modules are used.

Canonical Example Flows

Flow A: Full Generation (Playbook)

User prompt: "Create a playbook to deploy nginx with TLS on Ubuntu and RHEL."

1. Classify as full-generation.
2. Gather/confirm required inputs (hosts, cert paths, become, service name).
3. Extract required references (best-practices.md, module-patterns.md) and playbook template.
4. Generate complete playbook with OS conditionals (apt/dnf), handlers, validation for config templates.
5. Run ansible-validator.
6. Fix issues and rerun until checks pass (or apply matrix fallback if tooling unavailable).
7. Present output with validation summary, usage command, and prerequisites.

Flow B: Quick Snippet (Task Block)

User prompt: "Give me a snippet to create a user and SSH key."

1. Classify as snippet-only.
2. Extract minimal module patterns for ansible.builtin.user and ansible.builtin.authorized_key.
3. Generate concise snippet with FQCN, idempotency, and variable placeholders.
4. Perform inline sanity checks (YAML shape, FQCN, obvious idempotency/security).
5. Present snippet and note that full validator run was skipped due to snippet-only mode.

Output Requirements

For generated executable artifacts, use this response structure:

## Generated [Resource Type]: [Name]

**Validation Status:** [Passed / Partially validated / Skipped with reason]
- YAML syntax: [status]
- Ansible syntax: [status]
- Lint: [status]

**Summary:**
- [What was generated]
- [Key implementation choices]

**Assumptions:**
- [Defaults or inferred values]

**Usage:**
```bash
[Exact command(s)]

Prerequisites:

• [Collections, binaries, environment needs]

## Done Criteria

This skill execution is complete only when all applicable items are true:

- Trigger decision is explicit (`full-generation`, `snippet-only`, or `docs-only`).
- Required references/templates were consulted for the selected artifact type.
- Generated output has no unresolved placeholders.
- Validation followed default behavior or a documented exception from the matrix.
- Any skipped checks include a concrete reason and deferred command(s).
- Final output includes summary, assumptions, usage, and prerequisites.

Ansible Validator

Overview

Comprehensive toolkit for validating, linting, and testing Ansible playbooks, roles, and collections. This skill provides automated workflows for ensuring Ansible code quality, syntax validation, dry-run testing with check mode and molecule, and intelligent documentation lookup for custom modules and collections with version awareness.

Default behavior: When validating any Ansible role with a molecule/ directory, attempt Molecule automatically using bash scripts/test_role.sh <role-path>. If Molecule cannot run due to environment/runtime limits, mark Molecule as BLOCKED, report why, and continue all non-Molecule validation steps.

Trigger Guidance

Use this skill when the request is about validating or debugging existing Ansible code, not generating new code.

Common trigger phrases:

• "validate this playbook"
• "lint this role"
• "why is ansible-lint failing"
• "run check mode safely"
• "test this role with molecule"
• "find security issues in these Ansible files"
• "module not found in this collection"

When to Use This Skill

Apply this skill when encountering any of these scenarios:

• Working with Ansible files (.yml, .yaml playbooks, roles, inventories, vars)
• Validating Ansible playbook syntax and structure
• Linting and formatting Ansible code
• Performing dry-run testing with ansible-playbook --check
• Testing roles and playbooks with Molecule
• Debugging Ansible errors or misconfigurations
• Understanding custom Ansible modules, collections, or roles
• Ensuring infrastructure-as-code best practices
• Security validation of Ansible playbooks
• Version compatibility checks for collections and modules

Preflight (Run First)

Run preflight before validation to avoid dead ends:

bash scripts/setup_tools.sh

Command path assumption: run commands from this skill root (devops-skills-plugin/skills/ansible-validator) or use absolute paths.

Preflight requirements:

• Baseline validation: ansible, ansible-playbook, ansible-lint (plus yamllint recommended)
• Molecule execution: molecule plus an available runtime (docker or podman)
• Security scanning: checkov (wrapper can bootstrap if missing)

Deterministic fallback rules:

• If baseline tools are missing but Python + pip are available, wrapper scripts bootstrap temporary environments automatically.
• If wrapper bootstrap fails (offline index, pip failure, missing Python), run direct commands for available tools, mark missing stages as BLOCKED, and continue.
• If Molecule runtime is unavailable (Docker/Podman missing or daemon not running), skip Molecule execution, mark as BLOCKED, and continue remaining stages.

Wrapper vs Direct Command Routing

Use wrappers by default for consistent behavior and fallback handling.

Validation Workflow

Follow this deterministic workflow and never stop at a missing dependency:

0. Preflight
   ├─> Run: bash scripts/setup_tools.sh
   ├─> Record tool/runtime readiness
   └─> Continue even when optional tools are missing

1. Identify scope
   ├─> Single playbook validation
   ├─> Role validation
   ├─> Collection validation
   └─> Multi-playbook/inventory validation

2. Syntax Validation
   ├─> Run ansible-playbook --syntax-check
   ├─> Run yamllint for YAML syntax
   └─> Report as PASS/FAIL/BLOCKED

3. Lint and Best Practices
   ├─> Run ansible-lint (comprehensive linting)
   ├─> Check for deprecated modules (see references/module_alternatives.md)
   ├─> **DETECT NON-FQCN MODULE USAGE** (apt vs ansible.builtin.apt)
   │   └─> Run bash scripts/check_fqcn.sh to identify short module names
   │   └─> Recommend FQCN alternatives from references/module_alternatives.md
   ├─> Verify role structure
   └─> Report linting issues

4. Dry-Run Testing (check mode)
   ├─> Run ansible-playbook --check (if inventory available)
   ├─> Analyze what would change
   └─> Report potential issues

5. Molecule Testing (for roles with molecule/) - AUTOMATIC ATTEMPT
   ├─> Check if molecule/ directory exists in role
   ├─> If present, run: bash scripts/test_role.sh <role-path> [scenario]
   ├─> If script exits 2, mark Molecule as BLOCKED (environment/runtime issue)
   ├─> If script exits 1, mark Molecule as FAIL (role/test issue)
   └─> Continue remaining validation regardless of Molecule outcome

6. Custom Module/Collection Analysis (if detected)
   ├─> Extract module/collection information
   ├─> Identify versions
   ├─> Lookup documentation (Context7 first, then web.search_query fallback)
   └─> Provide version-specific guidance

7. Security and Best Practices Review - DUAL SCANNING DEFAULT
   ├─> Run bash scripts/validate_playbook_security.sh or validate_role_security.sh (Checkov)
   ├─> Run bash scripts/scan_secrets.sh for hardcoded secret detection
   │   └─> This catches secrets Checkov may miss (passwords, API keys, tokens)
   ├─> If one scanner is unavailable, run the other and report reduced coverage
   ├─> Validate privilege escalation
   ├─> Review file permissions
   └─> Identify common anti-patterns

8. Reference Routing
   ├─> Map each error/warning class to the matching reference file
   ├─> Extract concrete remediation from references (not file-name-only mention)
   └─> Include source section + fix guidance in final report

9. Final Report (required format)
   ├─> Summary counts: PASS / FAIL / BLOCKED / SKIPPED
   ├─> Findings grouped by severity
   ├─> Tool/runtime blockers with exact command that failed
   └─> Next actions to reach full validation coverage

Status contract: BLOCKED means validation could not run due to environment/runtime constraints; FAIL means the Ansible code or tests failed.

Error-Class Reference Routing

When issues are detected, consult the mapped reference and include a specific remediation excerpt in the report.

External documentation lookup trigger:

• If the issue involves a custom/private collection or unknown module parameters not covered locally, run module discovery + documentation lookup (see section 7).

Core Capabilities

1. YAML Syntax Validation

Purpose: Ensure YAML files are syntactically correct before Ansible parsing.

Tools:

• yamllint - YAML linter for syntax and formatting
• ansible-playbook --syntax-check - Ansible-specific syntax validation

Workflow:

# Check YAML syntax with yamllint
yamllint playbook.yml

# Or for entire directory
yamllint -c .yamllint .

# Check Ansible playbook syntax
ansible-playbook playbook.yml --syntax-check

Common Issues Detected:

• Indentation errors
• Invalid YAML syntax
• Duplicate keys
• Trailing whitespace
• Line length violations
• Missing colons or quotes

Best Practices:

• Always run yamllint before ansible-lint
• Use 2-space indentation consistently
• Configure yamllint rules in .yamllint
• Fix YAML syntax errors first, then Ansible-specific issues

2. Ansible Lint

Purpose: Enforce Ansible best practices and catch common errors.

Workflow:

# Lint a single playbook
ansible-lint playbook.yml

# Lint all playbooks in directory
ansible-lint .

# Lint with specific rules
ansible-lint -t yaml,syntax playbook.yml

# Skip specific rules
ansible-lint -x yaml[line-length] playbook.yml

# Output parseable format
ansible-lint -f pep8 playbook.yml

# Show rule details
ansible-lint -L

Common Issues Detected:

• Deprecated modules or syntax
• Missing task names
• Improper use of command vs shell
• Unquoted template expressions
• Hard-coded values that should be variables
• Missing become directives
• Inefficient task patterns
• Jinja2 template errors
• Incorrect variable usage
• Role dependencies issues

Severity Levels:

• Error: Must fix - will cause failures
• Warning: Should fix - potential issues
• Info: Consider fixing - best practice violations

Auto-fix approach:

• ansible-lint supports --fix for auto-fixable issues
• Always review changes before applying
• Some issues require manual intervention

3. Security Scanning (Checkov)

Purpose: Identify security vulnerabilities and compliance violations in Ansible code using Checkov, a static code analysis tool for infrastructure-as-code.

What Checkov Provides Beyond ansible-lint:

While ansible-lint focuses on code quality and best practices, Checkov specifically targets security policies and compliance:

• SSL/TLS Security: Certificate validation enforcement
• HTTPS Enforcement: Ensures secure protocols for downloads
• Package Security: GPG signature verification for packages
• Cloud Security: AWS, Azure, GCP misconfiguration detection
• Compliance Frameworks: Maps to security standards
• Network Security: Firewall and network policy validation

Workflow:

# Scan playbook for security issues
bash scripts/validate_playbook_security.sh playbook.yml

# Scan entire directory
bash scripts/validate_playbook_security.sh /path/to/playbooks/

# Scan role for security issues
bash scripts/validate_role_security.sh roles/webserver/

# Direct checkov usage
checkov -d . --framework ansible

# Scan with specific output format
checkov -d . --framework ansible --output json

# Scan and skip specific checks
checkov -d . --framework ansible --skip-check CKV_ANSIBLE_1

Common Security Issues Detected:

Certificate Validation:

• CKV_ANSIBLE_1: URI module disabling certificate validation
• CKV_ANSIBLE_2: get_url disabling certificate validation
• CKV_ANSIBLE_3: yum disabling certificate validation
• CKV_ANSIBLE_4: yum disabling SSL verification

HTTPS Enforcement:

• CKV2_ANSIBLE_1: URI module using HTTP instead of HTTPS
• CKV2_ANSIBLE_2: get_url using HTTP instead of HTTPS

Package Security:

• CKV_ANSIBLE_5: apt installing packages without GPG signature
• CKV_ANSIBLE_6: apt using force parameter bypassing signatures
• CKV2_ANSIBLE_4:* dnf installing packages without GPG signature
• CKV2_ANSIBLE_5: dnf disabling SSL verification
• CKV2_ANSIBLE_6: dnf disabling certificate validation

Error Handling:

• CKV2_ANSIBLE_3: Block missing error handling

Cloud Security (when managing cloud resources):

• CKV_AWS_88: EC2 instances with public IPs
• CKV_AWS_135: EC2 instances without EBS optimization

Example Violation:

# BAD - Disables certificate validation
- name: Download file
  get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    validate_certs: false  # Security issue!

# GOOD - Certificate validation enabled
- name: Download file
  get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    validate_certs: true  # Or omit (true by default)

Integration with Validation Workflow:

Checkov complements ansible-lint:

1. ansible-lint catches code quality issues, deprecated modules, best practices
2. Checkov catches security vulnerabilities, compliance violations, cryptographic issues

Best Practice: Run both tools for comprehensive validation:

# Complete validation workflow
bash scripts/validate_playbook.sh playbook.yml         # Syntax + Lint
bash scripts/validate_playbook_security.sh playbook.yml  # Security

Output Format:

Checkov provides clear security scan results:

Security Scan Results:
  Passed:  15 checks
  Failed:  2 checks
  Skipped: 0 checks

Failed Checks:
  Check: CKV_ANSIBLE_2 - "Ensure that certificate validation isn't disabled with get_url"
    FAILED for resource: tasks/main.yml:download_file
    File: /roles/webserver/tasks/main.yml:10-15

Remediation Resources:

• Checkov Policy Index: https://www.checkov.io/5.Policy%20Index/ansible.html
• Ansible Security Checklist: references/security_checklist.md
• Ansible Best Practices: references/best_practices.md

Installation:

Checkov is automatically installed in a temporary environment if not available system-wide. For permanent installation:

pip3 install checkov

When to Use:

• Before deploying to production
• In CI/CD pipelines for automated security checks
• When working with sensitive infrastructure
• For compliance audits and security reviews
• When downloading files or installing packages
• When managing cloud resources with Ansible

4. Playbook Syntax Check

Purpose: Validate playbook syntax without executing tasks.

Workflow:

# Basic syntax check
ansible-playbook playbook.yml --syntax-check

# Syntax check with inventory
ansible-playbook -i inventory playbook.yml --syntax-check

# Syntax check with extra vars
ansible-playbook playbook.yml --syntax-check -e @vars.yml

# Check all playbooks
for file in *.yml; do
  ansible-playbook "$file" --syntax-check
done

Validation Checks:

• YAML parsing
• Playbook structure
• Task definitions
• Variable references
• Module parameter syntax
• Jinja2 template syntax
• Include/import statements

Error Handling:

• Parse error messages for specific issues
• Check for typos in module names
• Verify variable definitions
• Ensure proper indentation
• Check file paths for includes/imports

5. Dry-Run Testing (Check Mode)

Purpose: Preview changes that would be made without actually applying them.

Workflow:

# Run in check mode (dry-run)
ansible-playbook -i inventory playbook.yml --check

# Check mode with diff
ansible-playbook -i inventory playbook.yml --check --diff

# Check mode with verbose output
ansible-playbook -i inventory playbook.yml --check -v

# Check mode for specific hosts
ansible-playbook -i inventory playbook.yml --check --limit webservers

# Check mode with tags
ansible-playbook -i inventory playbook.yml --check --tags deploy

# Step through tasks
ansible-playbook -i inventory playbook.yml --check --step

Check Mode Analysis:

When reviewing check mode output, focus on:

1. Task Changes:

   • ok: No changes needed
   • changed: Would make changes
   • failed: Would fail (check for check_mode support)
   • skipped: Conditional skip

2. Diff Output:

   • Shows exact changes to files
   • Helps identify unintended modifications
   • Useful for reviewing template changes

3. Handlers:

   • Which handlers would be notified
   • Service restarts that would occur
   • Potential downtime

4. Failed Tasks:

   • Some modules don't support check mode
   • May need check_mode: no override
   • Identify tasks that would fail

Limitations:

• Not all modules support check mode
• Some tasks depend on previous changes
• May not accurately reflect all changes
• Stateful operations may show unexpected results

Safety Considerations:

• Always run check mode before real execution
• Review diff output carefully
• Test in non-production first
• Validate changes make sense
• Check for unintended side effects

6. Molecule Testing

Purpose: Test Ansible roles in isolated environments with multiple scenarios.

Automatic attempt policy: When validating any Ansible role with a molecule/ directory, automatically attempt Molecule tests using bash scripts/test_role.sh <role-path> [scenario].

When to Use:

• Automatically triggered when validating roles with molecule/ directory
• Testing roles before deployment
• Validating role compatibility across different OS versions
• Integration testing for complex roles
• CI/CD pipeline validation

Workflow:

# Initialize molecule for a role
cd roles/myrole
molecule init scenario --driver-name docker

# List scenarios
molecule list

# Run full test sequence
molecule test

# Individual test stages
molecule create      # Create test instances
molecule converge    # Run Ansible against instances
molecule verify      # Run verification tests
molecule destroy     # Destroy test instances

# Test with specific scenario
molecule test -s alternative

# Debug mode
molecule --debug test

# Keep instances for debugging
molecule converge
molecule login       # SSH into test instance

Test Sequence:

1. dependency - Install role dependencies
2. lint - Run yamllint and ansible-lint
3. cleanup - Clean up before testing
4. destroy - Destroy existing instances
5. syntax - Run syntax check
6. create - Create test instances
7. prepare - Prepare instances (install requirements)
8. converge - Run the role
9. idempotence - Run again, verify no changes
10. side_effect - Optional side effect playbook
11. verify - Run verification tests (Testinfra, etc.)
12. cleanup - Final cleanup
13. destroy - Destroy test instances

Molecule Configuration:

Check molecule/default/molecule.yml:

dependency:
  name: galaxy
driver:
  name: docker
platforms:
  - name: instance
    image: ubuntu:22.04
provisioner:
  name: ansible
verifier:
  name: ansible

Verification Tests:

Molecule supports multiple verifiers:

• Ansible (built-in): Use Ansible tasks to verify
• Testinfra: Python-based infrastructure tests
• Goss: YAML-based server validation

Example Ansible verifier (molecule/default/verify.yml):

---
- name: Verify
  hosts: all
  tasks:
    - name: Check service is running
      service:
        name: nginx
        state: started
      check_mode: true
      register: result
      failed_when: result.changed

Common Molecule Errors:

• Driver not installed (docker, podman, vagrant)
• Missing Python dependencies
• Platform image not available
• Network connectivity issues
• Insufficient permissions for driver

Molecule Skip/Fallback Policy (Required):

• If molecule/ does not exist: mark Molecule as SKIPPED and continue.
• If test_role.sh exits 2: mark Molecule as BLOCKED (missing/unavailable runtime dependency) and continue.
• If test_role.sh exits 1: mark Molecule as FAIL (role/test issue) and continue.
• Never stop the full validation report because Molecule is blocked.

Use this reporting language for blocked Molecule runs:

Molecule Status: BLOCKED
Reason: <missing dependency/runtime and failing command>
Fallback Applied: Completed syntax, lint, check-mode, and security validation without Molecule runtime tests.
Next Action: <install/start dependency>; rerun `bash scripts/test_role.sh <role-path> [scenario]`

7. Custom Module and Collection Documentation Lookup

Purpose: Automatically discover and retrieve version-specific documentation for custom modules and collections using web search and Context7 MCP.

When to Trigger:

• Encountering unfamiliar module usage
• Working with custom/private collections
• Debugging module-specific errors
• Understanding new module parameters
• Checking version compatibility
• Deprecated module alternatives

Detection Workflow:

1. Extract Module Information:

   • Use scripts/extract_ansible_info_wrapper.sh to parse playbooks and roles
   • Identify module usage and collections
   • Extract version constraints from requirements.yml

2. Extract Collection Information:

   • Identify collection namespaces (e.g., community.general, ansible.posix)
   • Determine collection versions from requirements.yml or galaxy.yml
   • Detect custom/private vs. public collections

Documentation Lookup Strategy:

Use this deterministic lookup order:

1. For public collections/modules:
   • Resolve library: mcp__context7__resolve-library-id
   • Query docs: mcp__context7__query-docs
2. If Context7 has no suitable result:
   • Use web search via web.search_query with versioned queries
   • Prioritize official docs (docs.ansible.com, galaxy.ansible.com, vendor docs)
3. For custom/private modules:
   • Prefer in-repo docs (README, module docs, role docs) first
   • Then use targeted web search with collection/module/version terms
4. Always report source + version context used in final guidance

Search Query Templates:

# For custom modules
"[module-name] ansible module version [version] documentation"
"[module-name] ansible [module-type] example"
"ansible [collection-name].[module-name] parameters"

# For custom collections
"ansible collection [collection-name] version [version]"
"[collection-namespace].[collection-name] ansible documentation"
"ansible galaxy [collection-name] modules"

# For specific errors
"ansible [module-name] error: [error-message]"
"ansible [collection-name] module failed"

Example Workflow:

User working with: community.docker.docker_container version 3.0.0

1. Extract module info from playbook:
   tasks:
     - name: Start container
       community.docker.docker_container:
         name: myapp
         image: nginx:latest

2. Detect collection: community.docker

3. Search for documentation:
   - Try Context7: mcp__context7__resolve-library-id("ansible community.docker")
   - Fallback to web.search_query("ansible community.docker collection version 3.0 docker_container module documentation")

4. If official docs found:
   - Parse module parameters (required vs optional)
   - Identify return values
   - Find usage examples
   - Check version compatibility

5. Provide version-specific guidance to user

Version Compatibility Checks:

• Compare required collection versions with available versions
• Identify deprecated modules or parameters
• Suggest upgrade paths if using outdated versions
• Warn about breaking changes between versions
• Check Ansible core version compatibility

Common Collection Sources:

• Ansible Galaxy: Official community collections
• Red Hat Automation Hub: Certified collections
• GitHub: Custom/private collections
• Internal repositories: Company-specific collections

8. Security and Best Practices Validation

Purpose: Identify security vulnerabilities and anti-patterns in Ansible playbooks.

Security Checks:

1. Secrets Detection:

   # Check for hardcoded credentials
   grep -r "password:" *.yml
   grep -r "secret:" *.yml
   grep -r "api_key:" *.yml
   grep -r "token:" *.yml
   

   Remediation: Use Ansible Vault, environment variables, or external secret management

2. Privilege Escalation:

   • Unnecessary use of become: yes
   • Missing become_user specification
   • Over-permissive sudo rules
   • Running entire playbooks as root

3. File Permissions:

   • World-readable sensitive files
   • Missing mode parameter on file/template tasks
   • Incorrect ownership settings
   • Sensitive files not encrypted with vault

4. Command Injection:

   • Unvalidated variables in shell/command modules
   • Missing quote filter for user input
   • Direct use of {{ var }} in command strings

5. Network Security:

   • Unencrypted protocols (HTTP instead of HTTPS)
   • Missing SSL/TLS validation
   • Exposing services on 0.0.0.0
   • Insecure default ports

Best Practices:

1. Playbook Organization:

   • Logical task separation
   • Reusable roles for common patterns
   • Clear directory structure
   • Meaningful playbook names

2. Variable Management:

   • Vault encryption for sensitive data
   • Clear variable naming conventions
   • Variable precedence awareness
   • Group/host vars organization
   • Default values using default() filter

3. Task Naming:

   • Descriptive task names
   • Consistent naming convention
   • Action-oriented descriptions
   • Include changed resource in name

4. Idempotency:

   • All tasks should be idempotent
   • Use proper modules instead of command/shell
   • Check mode compatibility
   • Proper use of creates, removes for command tasks
   • Avoid changed_when: false unless necessary

5. Error Handling:

   • Use failed_when for custom failure conditions
   • Implement block/rescue/always for error recovery
   • Set appropriate any_errors_fatal
   • Use ignore_errors sparingly

6. Documentation:

   • README for each role
   • Variable documentation in defaults/main.yml
   • Role metadata in meta/main.yml
   • Playbook header comments

Reference Documentation:

For detailed security guidelines and best practices, refer to:

• references/security_checklist.md - Common security vulnerabilities
• references/best_practices.md - Ansible coding standards
• references/common_errors.md - Common errors and solutions

Tool Prerequisites

Run this preflight before validation:

# Preferred one-shot preflight
bash scripts/setup_tools.sh

# Check Ansible installation
ansible --version
ansible-playbook --version

# Check ansible-lint installation
ansible-lint --version

# Check yamllint installation
yamllint --version

# Check molecule installation (for role testing with molecule/)
molecule --version

# Check container runtime for Molecule
docker --version
docker info
# or
podman --version
podman info

# Install missing tools (example for pip)
pip install ansible ansible-lint yamllint ansible-compat

# Install molecule with docker driver
pip install molecule molecule-docker

# Install molecule with podman driver (alternative)
pip install molecule molecule-podman

Minimum Versions:

• Ansible: >= 2.9 (recommend >= 2.12)
• ansible-lint: >= 6.0.0
• yamllint: >= 1.26.0
• molecule: >= 3.4.0 (if testing roles)

Execution policy when tools are missing:

• If ansible/ansible-lint are missing, wrappers (validate_playbook.sh, validate_role.sh) attempt temporary venv bootstrap.
• If Molecule runtime (docker info or podman info) is unavailable, Molecule is BLOCKED and non-Molecule checks continue.
• If checkov is missing, security wrappers bootstrap it when possible; otherwise run scan_secrets.sh and report reduced security coverage.

Optional Tools:

• ansible-inventory - Inventory validation and graphing
• ansible-doc - Module documentation lookup
• jq - JSON parsing for structured output

Error Troubleshooting

Common Errors and Solutions

Error: Module Not Found

Solution: Install required collection with ansible-galaxy
Check collections/requirements.yml
Verify collection namespace and name

Error: Undefined Variable

Solution: Define variable in vars, defaults, or group_vars
Check variable precedence
Use default() filter for optional variables
Verify variable file is included

Error: Template Syntax Error

Solution: Check Jinja2 template syntax
Verify variable types match filters
Ensure proper quote escaping
Test template rendering separately

Error: Connection Failed

Solution: Verify inventory host accessibility
Check SSH configuration and keys
Verify ansible_host and ansible_port
Test with ansible -m ping

Error: Permission Denied

Solution: Add become: yes for privilege escalation
Verify sudo/su configuration
Check file permissions
Verify user has necessary privileges

Error: Deprecated Module

Solution: Check ansible-lint output for replacement
Consult module documentation for alternatives
Update to recommended module
Test functionality with new module

Resources

scripts/

setup_tools.sh - Preflight checker for Ansible validator dependencies. Verifies baseline tools (ansible, ansible-playbook, ansible-lint, yamllint) and Molecule runtime readiness (docker/podman) and provides installation guidance.

Usage:

bash scripts/setup_tools.sh

extract_ansible_info_wrapper.sh - Bash wrapper for extract_ansible_info.py that automatically handles PyYAML dependencies. Creates a temporary venv if PyYAML is not available in system Python.

Usage:

bash scripts/extract_ansible_info_wrapper.sh <path-to-playbook-or-role>

Output: JSON structure with modules, collections, and versions

extract_ansible_info.py - Python script (called by wrapper) to parse Ansible playbooks and roles to extract module usage, collection dependencies, and version information. The wrapper script handles dependency management automatically.

validate_playbook.sh - Comprehensive validation script that runs syntax check, yamllint, and ansible-lint on playbooks. Automatically installs ansible and ansible-lint in a temporary venv if not available on the system (prefers system versions when available).

Usage:

bash scripts/validate_playbook.sh <playbook.yml>

validate_playbook_security.sh - Security validation script that scans playbooks for security vulnerabilities using Checkov. Automatically installs checkov in a temporary venv if not available. Complements validate_playbook.sh by focusing on security-specific checks like SSL/TLS validation, HTTPS enforcement, and package signature verification.

Usage:

bash scripts/validate_playbook_security.sh <playbook.yml>
# Or scan entire directory
bash scripts/validate_playbook_security.sh /path/to/playbooks/

validate_role.sh - Comprehensive role validation script that checks role structure, YAML syntax, Ansible syntax, linting, and molecule configuration.

Usage:

bash scripts/validate_role.sh <role-directory>

Validates:

• Role directory structure (required and recommended directories)
• Presence of main.yml files in each directory
• YAML syntax across all role files
• Ansible syntax using a test playbook
• Best practices with ansible-lint
• Molecule test configuration

validate_role_security.sh - Security validation script for Ansible roles using Checkov. Scans entire role directory for security issues. Automatically installs checkov in a temporary venv if not available. Complements validate_role.sh with security-focused checks.

Usage:

bash scripts/validate_role_security.sh <role-directory>

test_role.sh - Wrapper script for Molecule testing with automatic dependency installation. If molecule is missing, it creates a temporary venv and installs dependencies. Returns exit code 2 for environment/runtime blockers (for example missing Docker/Podman runtime) and exit code 1 for role/test failures.

Usage:

bash scripts/test_role.sh <role-directory> [scenario]

scan_secrets.sh - Comprehensive secret scanner that uses grep-based pattern matching to detect hardcoded secrets in Ansible files. Complements Checkov security scanning by catching secrets that static analysis may miss, including passwords, API keys, tokens, AWS credentials, and private keys.

Usage:

bash scripts/scan_secrets.sh <playbook.yml|role-directory|directory>

Detects:

• Hardcoded passwords and credentials
• API keys and tokens
• AWS access keys and secret keys
• Database connection strings with embedded credentials
• Private key content (RSA, OpenSSH, EC, DSA)

IMPORTANT: This script should ALWAYS be run alongside Checkov (validate_*_security.sh) for comprehensive security scanning. Checkov catches SSL/TLS and protocol issues; this script catches hardcoded secrets.

check_fqcn.sh - Scans Ansible files to identify modules using short names instead of Fully Qualified Collection Names (FQCN). Recommends migration to ansible.builtin.* or appropriate collection namespace for better clarity and future compatibility.

Usage:

bash scripts/check_fqcn.sh <playbook.yml|role-directory|directory>

Detects:

• ansible.builtin modules (apt, yum, copy, file, template, service, etc.)
• community.general modules (ufw, docker_container, timezone, etc.)
• ansible.posix modules (synchronize, acl, firewalld, etc.)

Provides specific migration recommendations with FQCN alternatives.

validate_inventory.sh - Validates Ansible inventory files and directories. Checks YAML syntax, resolves host/group hierarchy, and flags common structural issues such as plaintext credentials and missing ansible_connection=local for localhost entries. Automatically installs ansible in a temporary venv if not available.

Usage:

bash scripts/validate_inventory.sh <inventory-file|inventory-directory>

Validation stages:

1. YAML syntax check (yamllint) on all inventory YAML files
2. Inventory parse — ansible-inventory --list to verify host/group resolution
3. Host graph — ansible-inventory --graph to display group hierarchy
4. Structural checks — plaintext passwords, localhost connection settings, group_vars/host_vars presence

references/

security_checklist.md - Comprehensive security validation checklist for Ansible playbooks covering secrets management, privilege escalation, file permissions, and command injection.

best_practices.md - Ansible coding standards and best practices for playbook organization, variable handling, task naming, idempotency, and documentation.

common_errors.md - Database of common Ansible errors with detailed solutions and prevention strategies.

module_alternatives.md - Guide for replacing deprecated modules with current alternatives.

assets/

.yamllint - Pre-configured yamllint rules for Ansible YAML files.

.ansible-lint - Pre-configured ansible-lint configuration with reasonable rule settings.

molecule.yml.template - Template molecule configuration for role testing.

Workflow Examples

Example 1: Validate a Single Playbook

User: "Check if this playbook.yml file is valid"

Steps:
1. Run preflight: `bash scripts/setup_tools.sh`
2. Run wrapper: `bash scripts/validate_playbook.sh playbook.yml`
3. If inventory is provided, run check mode: `ansible-playbook -i <inventory> playbook.yml --check --diff`
4. Run security wrappers:
   - `bash scripts/validate_playbook_security.sh playbook.yml`
   - `bash scripts/scan_secrets.sh playbook.yml`
5. If custom modules are detected, run docs lookup workflow (Context7 first, web fallback)
6. Report results with PASS/FAIL/BLOCKED/SKIPPED counts and remediation steps

Example 2: Validate an Ansible Role

User: "Validate my ansible role in ./roles/webserver/"

Steps:
1. Run preflight: `bash scripts/setup_tools.sh`
2. Run role wrapper: `bash scripts/validate_role.sh ./roles/webserver/`
3. This checks:
   - Role directory structure (tasks/, defaults/, handlers/, meta/, etc.)
   - Required main.yml files
   - YAML syntax with yamllint
   - Ansible syntax with ansible-playbook
   - Best practices with ansible-lint
   - Molecule configuration (if present)
4. If `molecule/` exists, attempt Molecule automatically:
   - `bash scripts/test_role.sh ./roles/webserver/`
   - Exit `2`: report `Molecule Status: BLOCKED` with reason, continue remaining checks
   - Exit `1`: report `Molecule Status: FAIL` with debugging guidance
5. Run role security checks:
   - `bash scripts/validate_role_security.sh ./roles/webserver/`
   - `bash scripts/scan_secrets.sh ./roles/webserver/`
6. If custom modules detected, run documentation lookup workflow
7. Provide final report with severity, blockers, and rerun actions

Example 3: Dry-Run Testing for Production

User: "Run playbook in check mode for production servers"

Steps:
1. Verify inventory file exists
2. Run ansible-playbook --check --diff -i production
3. Analyze check mode output
4. Highlight tasks that would change
5. Review handler notifications
6. Flag any security concerns
7. Provide recommendation on safety of applying

Example 4: Understanding Custom Collection Module

User: "I'm using community.postgresql.postgresql_db version 2.3.0, what parameters are available?"

Steps:
1. Try Context7 MCP: `mcp__context7__resolve-library-id("ansible community.postgresql")`
2. If found, query docs with `mcp__context7__query-docs` for `postgresql_db`
3. If not found, use `web.search_query`: "ansible community.postgresql version 2.3.0 postgresql_db module documentation"
4. Extract module parameters (required vs optional)
5. Provide examples of common usage patterns
6. Note any version-specific considerations

Example 5: Testing Role with Molecule

User: "Test my nginx role with molecule"

Steps:
1. Check if molecule is configured in role
2. Run preflight (`bash scripts/setup_tools.sh`) and confirm Docker/Podman runtime availability
3. Run `bash scripts/test_role.sh <role-path> [scenario]`
4. If exit code is `2`, mark Molecule `BLOCKED`, report reason, and continue non-Molecule checks
5. If exit code is `1`, inspect converge/verify output and report role issues
6. Analyze idempotency, syntax, and verification outcomes
7. Suggest improvements and exact rerun command

Integration with Other Skills

This skill works well in combination with:

• k8s-yaml-validator - When Ansible manages Kubernetes resources
• terraform-validator - When Ansible and Terraform are used together
• k8s-debug - For debugging infrastructure managed by Ansible

Notes

• Run stages in order: preflight -> syntax -> lint/FQCN -> check mode -> Molecule (when applicable) -> security -> reference routing -> final report.
• Use wrapper scripts as default execution path; switch to direct commands only when user asks or when wrapper bootstrapping is blocked.
• Treat missing dependencies/runtime as BLOCKED (not silent skip), and continue with remaining stages.
• For every detected issue class, include mapped reference guidance (common_errors, best_practices, module_alternatives, security_checklist).
• Always include explicit rerun commands for failed or blocked stages.

Done Criteria

This skill execution is complete when:

• Preflight status for required tools is reported (ansible, ansible-lint, and Molecule runtime status when role tests are in scope).
• Validation produces deterministic stage outcomes using PASS, FAIL, BLOCKED, and SKIPPED.
• Molecule never dead-ends the full validation flow; blocked runtime conditions are reported with fallback language.
• Wrapper-vs-direct command choice is explicit and justified.
• Reference lookups are tied to the actual error classes found, with concrete remediation guidance.

Azure Pipelines Generator

Generate production-ready Azure DevOps pipeline YAML with deterministic steps, explicit fallbacks, and clear completion criteria.

Trigger Guidance

Use this skill when the user asks to generate or redesign Azure Pipelines YAML, for example:

• "Create azure-pipelines.yml for my Node service."
• "Build a multi-stage Azure DevOps pipeline with staging and production."
• "Generate Azure pipeline templates for reuse across repos."
• "Convert this CI flow to Azure Pipelines."

Do not use this skill for validation-only requests. For validation-only work, use azure-pipelines-validator.

Execution Model

Normative keywords:

• MUST: required
• SHOULD: default unless user asks otherwise
• MAY: optional

Deterministic sequence:

1. Classify request mode.
2. Capture minimum required inputs.
3. Load minimum references (progressive disclosure).
4. Generate YAML using the quality checklist.
5. Validate (validator skill, script fallback, or manual fallback).
6. Return output in the required report format.

If a step cannot run due to environment limits, use the fallback in that step and continue.

1) Classify Request Mode

Choose exactly one primary mode:

• Basic CI: build/test/lint for one stack.
• Multi-stage CI/CD: build -> test -> deploy with environment tracking.
• Docker: image build/push and optional deploy.
• Kubernetes: image build/push plus Kubernetes deployment.
• Language-specific: .NET, Node.js, Python, Go, Java focused.
• Template-based: reusable templates plus thin root pipeline.
• Snippet-only: partial YAML requested, not full pipeline.

Mode-to-example mapping:

• Basic CI -> examples/basic-ci.yml
• Multi-stage CI/CD -> examples/multi-stage-cicd.yml
• .NET -> examples/dotnet-cicd.yml
• Python -> examples/python-cicd.yml
• Go -> examples/go-cicd.yml
• Kubernetes -> examples/kubernetes-deploy.yml
• Template-based -> examples/template-usage.yml + examples/templates/*.yml

2) Capture Required Inputs

Collect these before generation:

• App stack and package manager
• Build/test commands and report expectations
• Deployment target (none, Azure service, Docker registry, Kubernetes)
• Environment flow (dev/staging/prod) and branch gates
• Service connections, variable groups, secret handling
• Template requirement (yes/no)

Safe defaults when missing:

• CI branches: main, develop
• Production deploy branch: main only
• Agent image: pinned image (for example ubuntu-22.04)
• Deploy image tag: immutable ($(Build.BuildId)), never deploy latest

If key details are missing, state assumptions explicitly in final output.

3) Load References (Progressive Disclosure)

Read local references first.

Always read:

• docs/yaml-schema.md
• docs/best-practices.md

Read conditionally:

• docs/tasks-reference.md when selecting tasks/inputs
• docs/templates-guide.md only for template-based mode

Then read only the closest example(s) from the mode mapping above.

Fallback behavior for missing references:

• Missing example: use nearest mode example and note substitution.
• Missing doc section: continue with known conventions and mark uncertainty.
• Snippet-only request: read only the minimum needed for safe output.

The final response MUST include:

• References used
• References skipped or missing
• Impact

4) External Docs Escalation (Only When Needed)

Escalate beyond local docs only when:

• required task info is not in local docs
• task version compatibility is unclear
• troubleshooting a task-specific failure

Use this order:

1. Context7 (mcp__context7__resolve-library-id -> mcp__context7__query-docs)
2. Official docs search (Microsoft Learn first)

If network/tools are unavailable, proceed with best-known local guidance and add a residual-risk note.

5) Pipeline Generation Checklist

Apply all items below unless user asks for a narrow snippet.

Security:

• Never hardcode secrets.
• Use service connections and variable groups/secrets.
• Use immutable deploy image tags.

Versioning:

• Pin vmImage to explicit version, not *-latest.
• Pin task major versions (Task@N).
• @0 is allowed only when that task uses major 0.

Reliability:

• Use explicit dependsOn.
• Add timeoutInMinutes for long-running jobs.
• Use branch-gated deployment condition rules.
• Use deployment jobs with environment for deploy stages.

Performance:

• Use Cache@2 where it improves dependency install time.
• Use shallow checkout when full history is not required.
• Publish only required artifacts.

Testing/observability:

• Run lint/tests in CI.
• Publish test results with condition: succeededOrFailed().
• Publish coverage when available.

Maintainability:

• Add displayName for stages/jobs/key steps.
• Use templates when logic repeats.
• Add short comments only for non-obvious logic.

6) Validation Workflow

Default path (MUST for full pipeline generation):

1. Generate or update YAML.
2. Validate with azure-pipelines-validator.
3. Fix findings.
4. Re-run validation until no blocking issues remain.

Script fallback if validator skill is unavailable but local validator scripts exist:

bash devops-skills-plugin/skills/azure-pipelines-validator/scripts/validate_azure_pipelines.sh <pipeline-file>

Manual fallback when neither skill nor script can run:

1. YAML structure/indentation sanity
2. Hierarchy sanity (stages -> jobs -> steps)
3. Task format sanity (Task@Major)
4. Secret exposure scan (no plaintext credentials/tokens)
5. Deployment safety scan (environment usage, immutable deploy tags)

When fallback is used, final response MUST include:

• Validation status: Manual fallback
• Checks performed
• Residual risk

Validation MAY be skipped only for:

• snippet-only YAML
• documentation-only examples
• explicit user request to skip validation

7) Output Contract

Final response MUST include:

1. Pipeline YAML (or template set)
2. Required setup:
   • service connections
   • variable groups/secrets
   • environments and approvals/checks
3. Validation result:
   • validator status, script status, or manual fallback status
4. Assumptions
5. References used/skipped and impact
6. Optional next improvements

8) Canonical Example Flows

Example A: Full multi-stage generation

1. Select mode: Multi-stage CI/CD.
2. Capture stack/deploy/service-connection inputs.
3. Read docs/yaml-schema.md, docs/best-practices.md, and examples/multi-stage-cicd.yml.
4. Add requested customizations (stages, branch gates, environments, tasks).
5. Validate with azure-pipelines-validator; fix and re-run.
6. Return YAML + setup + validation + assumptions + references.

Example B: Quick snippet generation

1. Select mode: Snippet-only.
2. Read only the minimum required reference section.
3. Generate focused YAML snippet with safe defaults.
4. Skip full validation and state Validation status: Skipped (snippet-only).
5. Return snippet + assumptions + references.

9) Definition of Done

The execution is complete only when all applicable checks pass:

• Request mode is explicitly chosen.
• Assumptions are explicit for missing inputs.
• YAML follows checklist requirements (security, versioning, reliability, performance, maintainability).
• Validation path is documented (validator, script fallback, or manual fallback).
• Final response follows the output contract, including references and impact.

Azure Pipelines Validator

Use this skill to validate Azure DevOps pipeline YAML (azure-pipelines.yml / azure-pipelines.yaml) with local scripts first, then escalate to docs only when local output is not enough.

Trigger Phrases

Use this skill when the user asks things like:

• "Validate my azure-pipelines.yml."
• "Why is this Azure pipeline YAML failing?"
• "Run a security scan on this Azure DevOps pipeline."
• "Check this pipeline for best-practice issues."
• "Review this pipeline in CI before merge."

Do not use this skill for pipeline generation from scratch. Use azure-pipelines-generator for that.

Deterministic Path Setup (No Ambiguity)

Run from any directory using explicit absolute paths:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
SKILL_DIR="$REPO_ROOT/devops-skills-plugin/skills/azure-pipelines-validator"
PIPELINE_FILE="$REPO_ROOT/azure-pipelines.yml"

If REPO_ROOT is empty, stop and ask for the repository root path. Do not guess paths.

Validate one file:

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE"

Auto-detect from current directory (up to depth 3):

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh"

If auto-detect returns multiple files, rerun with one explicit file path.

Local-First Execution Model

1. Preflight

• Confirm bash and python3 are available.
• Confirm target file exists.

2. Run local validator

• Default full pass:

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE"

• Syntax only:

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --syntax-only

• Best practices only:

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --best-practices

• Security only:

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --security-only

• Strict mode (warnings fail):

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$PIPELINE_FILE" --strict

3. Interpret exit behavior

• 0: pass (or non-blocking checks only)
• 1: validation failed (blocking issues)
• 2: invalid invocation (missing/ambiguous file or bad args)

4. Return findings in the report format below.

Expected Report Format (Severity Buckets)

Always return results in this structure:

Validation Report: <path>

Summary:
- Blocking: <count>        # Syntax errors + Security critical/high
- Warning: <count>         # Security medium/low + best-practice warnings
- Info: <count>            # Suggestions
- Skipped: <count>         # Explicitly name skipped checks

Findings:
- [Blocking][syntax][<rule-id>] line <n> - <message>
- [Blocking][security-high][<rule-id>] line <n> - <message>
- [Warning][security-medium][<rule-id>] line <n> - <message>
- [Warning][best-practice][<rule-id>] line <n> - <message>
- [Info][best-practice][<rule-id>] line <n> - <message>

Remediation:
- <short, concrete fix per finding>

Execution Notes:
- Commands run: <exact commands>
- Environment/fallback notes: <tool missing, skipped checks, offline constraints>

Escalation Policy (Docs Only When Needed)

Run local checks first. Escalate only when at least one condition is true:

• Local finding depends on current upstream behavior (task versions, deprecations, new inputs).
• User asks for "latest/current/recent" Azure Pipelines task or schema details.
• Local scripts cannot determine validity for a specific task/resource syntax.

Escalation order:

1. Context7 docs tooling first.

mcp__context7__resolve-library-id(...)
mcp__context7__query-docs(...)

2. Official docs second (learn.microsoft.com / Microsoft Azure DevOps docs).
3. General web search only if the first two are insufficient.

When escalating, cite the source URL and state what local check could not answer.

Fallback Behavior

Use this matrix when tools are unavailable:

• Condition: yamllint unavailable.

• Action: Continue with syntax/best-practice/security checks.

• Report note: "YAML lint skipped because yamllint is unavailable."

• Condition: python3 unavailable or venv/dependency setup fails.

• Action: Mark scripted validation blocked; perform manual YAML review only if requested.

• Report note: "Local scripted validation blocked by missing Python runtime/dependencies."

• Condition: No network while dependencies/docs are needed.

• Action: Run whatever local checks are still possible; defer doc/version verification.

• Report note: "External verification deferred due offline environment."

• Condition: Multiple auto-detected pipeline files.

• Action: Do not pick arbitrarily; require explicit target file path.

• Report note: "Validation paused until a single target file is specified."

Rule Buckets (What the Scripts Check)

Syntax examples:

• yaml-syntax
• yaml-invalid-root
• invalid-hierarchy
• task-invalid-format
• pool-invalid
• deployment-missing-strategy

Best-practice examples:

• missing-displayname
• task-version-zero
• task-missing-version
• pool-latest-image
• missing-cache
• missing-deployment-condition

Security examples:

• hardcoded-password
• hardcoded-secret
• curl-pipe-shell
• eval-command
• insecure-ssl
• container-latest-tag
• variable-not-secret

Use script output rule IDs directly in the report.

References and Examples

• Syntax reference: docs/azure-pipelines-reference.md
• Example pipelines: examples/

Quick local test:

bash "$SKILL_DIR/scripts/validate_azure_pipelines.sh" "$SKILL_DIR/examples/basic-pipeline.yml"

Done Criteria

This skill execution is done when all conditions are true:

• Trigger match is explicit and plain-language examples are provided near the top.
• Validation command(s) were run with unambiguous paths.
• Report uses severity buckets (Blocking, Warning, Info, Skipped).
• Fallback behavior is explicitly reported for unavailable tools/environment constraints.
• External docs were consulted only when local checks were insufficient.

Bash Script Generator

Overview

Generate production-ready Bash scripts with clear requirements capture, deterministic generation flow, and validation-first iteration.

Trigger Phrases

Use this skill when the user asks to:

• Create, generate, write, or build a Bash/shell script
• Convert manual CLI steps into an automation script
• Build a text-processing script using grep, awk, or sed
• Create an operations helper script, cron script, or CI utility script

Do not use this skill for validating an existing script only. Use devops-skills:bash-script-validator for validation-only requests.

Execution Model

Follow stages in order. Do not skip a stage; use the documented fallback when blocked.

Stage 0: Preflight

1. Confirm scope and target output path.
2. Confirm shell target:

• Default: bash
• If portability is requested: POSIX sh

3. Check capabilities and pick fallback path:

If a fallback path is used, state it explicitly in the final summary.

Stage 1: Capture Requirements

Collect only what is needed to generate the script correctly:

• Input source and format
• Output destination and format
• Error handling behavior (fail-fast/retry/continue)
• Security constraints (sensitive data, privilege level)
• Performance constraints (large files, parallelism)
• Portability requirement (Bash-only vs POSIX)

Then create a Captured Requirements table with stable IDs.

## Captured Requirements

| Requirement ID | Description | Source | Implementation Plan |
|---|---|---|---|
| REQ-001 | Parse nginx logs from file input | User | `parse_args()` + `validate_file()` + `awk` parser |
| REQ-002 | Output top 10 errors | User | `analyze_errors()` + `sort | uniq -c | head -10` |
| REQ-003 | Handle large files efficiently | Assumption | Single-pass `awk`; avoid multi-pass loops |

Rules:

• Every major design decision maps to at least one REQ-*.
• Keep assumptions explicit and minimal.

Stage 2: Choose Generation Path

Use this deterministic decision tree:

Need multi-command architecture, unusual control flow, or strict non-template conventions?
├─ Yes -> Custom generation
└─ No
   Need standard CLI skeleton (usage/logging/arg parsing/cleanup)?
   ├─ Yes -> Template-first generation
   └─ No -> Custom generation

Template-first is the default for single-purpose CLI utilities.

Stage 3: Load Only Relevant References

Use progressive disclosure. Read only docs needed for the current request.

Citation format (required):

• [Ref: docs/<file>.md -> <section>]

Stage 4: Generate Script

Path A: Template-first (default)

1. Generate scaffold:

bash scripts/generate_script_template.sh standard output-script.sh

2. Replace placeholders and add business logic.
3. Keep logging to stderr and data output to stdout unless requirements say otherwise.
4. Add comments only where logic is non-obvious.

Path B: Custom generation

Build a script with at least:

• Shebang and strict mode
• usage()
• parse_args()
• Input validation and dependency checks
• Main workflow function(s)
• Predictable exit codes

Stage 5: Validate and Iterate

Default validation path:

1. Invoke devops-skills:bash-script-validator
2. Apply fixes
3. Re-run validation
4. Repeat until checks pass or blocker is identified

Fallback validation path (when validator skill is unavailable):

# Deterministic local gate for this skill:
bash scripts/run_ci_checks.sh --skip-shellcheck

# CI gate (shellcheck required):
bash scripts/run_ci_checks.sh --require-shellcheck

If any check is skipped, include Skipped check, Reason, and Risk in the output.

Stage 6: Final Response Contract

Always return:

1. Generated script path
2. Requirements traceability (REQ-* -> implementation)
3. Validation results with rerun status
4. Citations in standard format
5. Any assumptions/fallbacks used

Canonical Example Flows

Example A: Full Flow (Template-first)

1. Clarify missing data format and output expectations.
2. Capture REQ-* table.
3. Choose template-first path.
4. Generate scaffold with scripts/generate_script_template.sh.
5. Implement logic and map functions to REQ-*.
6. Validate with devops-skills:bash-script-validator and rerun until clean.
7. Return final summary with citations.

Example B: Constrained Environment Flow

Use this when AskUserQuestion, validator skill, or shellcheck is unavailable:

1. Ask clarifying questions in chat.
2. Mark unresolved items as assumptions in Captured Requirements.
3. Generate from template script or template file copy fallback.
4. Run bash -n (and sh -n if relevant).
5. If shellcheck is missing, report skip with risk and mitigation.

Done Criteria

The task is complete only when all items are true:

• Trigger matched and scope confirmed
• Captured Requirements table exists with REQ-* IDs
• Template-first vs custom decision is documented
• Script is generated with deterministic structure
• Validation executed and rerun policy applied
• Any skipped checks include explicit reason and risk
• Final response includes traceability, citations, and assumptions

Helper Scripts and Assets

• Script generator: scripts/generate_script_template.sh
• Deterministic CI gate: scripts/run_ci_checks.sh
• Regression test suite: scripts/test_generator.sh
• Standard scaffold: assets/templates/standard-template.sh
• Example output style: examples/log-analyzer.sh

Reference Docs

• docs/bash-scripting-guide.md
• docs/script-patterns.md
• docs/generation-best-practices.md
• docs/text-processing-guide.md

External References

• GNU Bash Manual
• POSIX Shell Specification
• ShellCheck

Bash Script Validator

Overview

This skill validates Bash and POSIX shell scripts with layered checks:

1. Syntax validation (bash -n or sh -n)
2. ShellCheck static analysis (system binary or wrapper fallback)
3. Custom security, portability, and optimization checks

Use the default flow below, then branch to fallbacks only when the environment is constrained.

Trigger Guidance

Use this skill when the request includes script quality, linting, syntax checking, or shell portability work.

Trigger Phrases

• "Validate this bash script"
• "Lint this .sh file"
• "Find security issues in this shell script"
• "Why does this script fail ShellCheck?"
• "Make this script POSIX compliant"
• "Review this shell script before CI"

Non-Trigger Examples

• General Linux command questions with no script file
• Kubernetes, Terraform, or pipeline validation tasks that do not involve shell scripts
• Pure prose editing tasks

Deterministic Execution Model

Run commands from this skill directory:

cd devops-skills-plugin/skills/bash-script-validator

Step 1: Preflight

1. Confirm target path exists and is readable.
2. Confirm bash is available.
3. Determine whether fixes can be applied directly (write access) or only suggested (read-only).

Step 2: Run Baseline Validation (Default Path)

bash scripts/validate.sh <script-path>

For deterministic stage behavior, set the ShellCheck provider explicitly:

# Modes: auto (default), system, wrapper, disabled
VALIDATOR_SHELLCHECK_MODE=system bash scripts/validate.sh <script-path>

Record:

• Detected shell type
• Exit code (0 clean, 1 warnings, 2 errors)
• All reported issue lines and ShellCheck codes (SC####) when present

Step 3: Load Only Needed References

Progressive disclosure by issue type:

• ShellCheck code explanations: docs/shellcheck-reference.md
• General fix patterns and security mistakes: docs/common-mistakes.md
• Bash-only behavior: docs/bash-reference.md
• POSIX portability or bashism fixes: docs/shell-reference.md
• Text-processing optimization issues: docs/grep-reference.md, docs/awk-reference.md, docs/sed-reference.md, docs/regex-reference.md (only when directly relevant)

Step 4: Provide or Apply Fixes

For each issue, include:

1. Exact location from validator output (line number and snippet)
2. Root cause
3. Corrected code
4. Why the change is safer or more portable
5. Subsection-level citation (format below)

If the request includes patching files and write access is available, apply fixes in small batches grouped by issue type.

Step 5: Rerun Policy (Mandatory After Changes)

After each batch of edits, rerun the validator:

bash scripts/validate.sh <script-path>

Rerun loop rules:

1. Continue until no new errors are introduced.
2. If warnings remain by design, document why they are intentionally accepted.
3. If constraints prevent full resolution, report unresolved items with a clear next action.
4. Always report the latest rerun exit code and remaining issue count.

Fallback Behavior

Use these branches only when the default flow cannot run as-is.

Citation Guidance for Fixes

Use subsection-level citations for every non-trivial fix.

Required citation format:

Reference: docs/<file>.md -> <Section> -> <Subsection>

Examples:

• Reference: docs/common-mistakes.md -> 1. Unquoted Variables -> Solution
• Reference: docs/shellcheck-reference.md -> SC2164: Use || exit After cd
• Reference: docs/shell-reference.md -> POSIX Best Practices -> 5. Avoid Bashisms

Citation rules:

1. Cite the most specific section that justifies the fix.
2. For ShellCheck findings, include both the SC#### code and the matching section.
3. If no exact subsection exists, cite the closest section and state that the fix is inferred from that guidance.

Response Template

Use this structure for deterministic output:

• Validation Results
• Command: bash scripts/validate.sh <script-path>
• Detected shell: <shell>
• Exit code: <code>
• Summary: <errors> errors, <warnings> warnings, <info> info
• Issue: <short label> (Line <n>)
• Problem:

  <problematic snippet>
  

• Fix:

  <corrected snippet>
  

• Why: <short explanation>
• Reference: docs/<file>.md -> <Section> -> <Subsection>
• Rerun command: bash scripts/validate.sh <script-path>
• Exit code after fixes: <code>
• Remaining issues: <count or none>

Example Flows

Fully Automated Environment

# 1) Baseline validation
bash scripts/validate.sh examples/bad-bash.sh

# 2) Apply fixes to target script
# 3) Rerun validation
bash scripts/validate.sh examples/bad-bash.sh

Expected behavior: full syntax + ShellCheck + custom-check coverage, with iterative reruns until stable.

Deterministic CI Gate

# Requires a system shellcheck binary.
bash scripts/run_ci_checks.sh

This runner enforces VALIDATOR_REQUIRE_SHELLCHECK=1 and VALIDATOR_SHELLCHECK_MODE=system so CI fails if the ShellCheck stage is skipped or unavailable.

Constrained Environment (No ShellCheck Runtime)

# shellcheck unavailable and wrapper cannot run
bash scripts/validate.sh examples/bad-shell.sh

Expected behavior: syntax + custom checks still run. Report reduced coverage and list what must be revalidated once ShellCheck is available.

Validator Script Details

Scripts

• scripts/validate.sh: primary validator entrypoint
• scripts/shellcheck_wrapper.sh: optional ShellCheck fallback using a cached Python virtual environment

Detection and Ordering

Validation order in scripts/validate.sh:

1. File checks (exists/readable/text)
2. Shebang-based shell detection
3. Syntax check
4. ShellCheck (or fallback/skip behavior)
5. Custom checks
6. Summary with exit code

Exit Codes

• 0: no issues found
• 1: warnings found
• 2: errors found

References

Load only what is needed:

• docs/bash-reference.md
• docs/shell-reference.md
• docs/shellcheck-reference.md
• docs/common-mistakes.md
• docs/grep-reference.md
• docs/awk-reference.md
• docs/sed-reference.md
• docs/regex-reference.md

Done Criteria

This skill update is complete when all are true:

1. Trigger guidance is explicit (positive and non-trigger examples).
2. Default workflow is deterministic and ordered.
3. Fallback behavior is explicit for missing tooling and constrained environments.
4. Fix explanations include subsection-level citations.
5. Post-fix rerun policy is mandatory and reported with exit codes.
6. Documentation supports both fully automated and constrained execution paths.

Dockerfile Generator

Overview

This skill provides a comprehensive workflow for generating production-ready Dockerfiles with security, optimization, and best practices built-in. Generates multi-stage builds, security-hardened configurations, and optimized layer structures with automatic validation and iterative error fixing.

Key Features:

• Multi-stage builds for optimal image size (50-85% reduction)
• Security hardening (non-root users, minimal base images, no secrets)
• Layer caching optimization for faster builds
• Language-specific templates (Node.js, Python, Go, Java)
• Automatic .dockerignore generation
• Integration with dockerfile-validator for validation
• Iterative validation and error fixing (minimum 1 iteration if errors found)
• Local references plus docs lookup fallback chain for framework-specific patterns

When to Use This Skill

Invoke this skill when:

• Creating new Dockerfiles from scratch
• Containerizing applications (Node.js, Python, Go, Java, or other languages)
• Implementing multi-stage builds for size optimization
• Converting existing Dockerfiles to best practices
• Generating production-ready container configurations
• Optimizing Docker builds for security and performance
• The user asks to "create", "generate", "build", or "write" a Dockerfile
• Implementing containerization for microservices
• Setting up CI/CD pipeline container builds

Trigger Phrases

Use this skill immediately when the request contains phrasing like:

• "Generate a production Dockerfile for my app"
• "Create a multi-stage Dockerfile for <language/framework>"
• "Containerize this service with security best practices"
• "Optimize this Dockerfile for size and build speed"
• "Write Dockerfile and .dockerignore for deployment"

Do NOT Use This Skill For

• Validating existing Dockerfiles (use dockerfile-validator instead)
• Building or running containers (use docker build/run commands)
• Debugging running containers (use docker logs, docker exec)
• Managing Docker images or registries

Deterministic Execution Model

Run these stages in order, and do not skip a stage unless the skip reason is reported in the final output.

1. Gather requirements (language, runtime version, entrypoint, exposed port, package manager, health endpoint).
2. Load references (local reference files first; external docs only when local references are insufficient).
3. Generate Dockerfile and .dockerignore.
4. Validate with dockerfile-validator or fallback local tools.
5. Iterate fixes until stop condition is met.
6. Publish final artifacts plus validation/audit report.

Stop conditions for stage 5:

• Stop when there are zero validation errors and no unapproved warnings.
• Stop after 3 iterations maximum, then emit an intentional-deviation report for unresolved findings.

Reference Path Map

Consult these files directly by path as needed:

• references/security_best_practices.md for non-root users, secret handling, base image hardening, vulnerability scanning.
• references/optimization_patterns.md for multi-stage strategy, cache optimization, layer reduction, BuildKit cache mounts.
• references/language_specific_guides.md for language/framework runtime and package-manager patterns.
• references/multistage_builds.md for advanced stage-splitting and artifact-copy patterns.

Dockerfile Generation Workflow

Follow this workflow when generating Dockerfiles. Adapt based on user needs:

Stage 1: Gather Requirements

Objective: Understand what needs to be containerized and gather all necessary information.

Information to Collect:

1. Application Details:

   • Programming language and version (Node.js 18/20, Python 3.11/3.12, Go 1.21+, Java 17/21, etc.)
   • Application type (web server, API, CLI tool, batch job, etc.)
   • Framework (Express, FastAPI, Spring Boot, etc.)
   • Entry point (main file, command to run)

2. Dependencies:

   • Package manager (npm/yarn/pnpm, pip/poetry, go mod, maven/gradle)
   • System dependencies (build tools, libraries, etc.)
   • Build-time vs runtime dependencies

3. Application Configuration:

   • Port(s) to expose
   • Environment variables needed
   • Configuration files
   • Health check endpoint (for web services)
   • Volume mounts (if any)

4. Build Requirements:

   • Build commands
   • Test commands (optional)
   • Compilation needs (for compiled languages)
   • Static asset generation

5. Production Requirements:

   • Expected image size constraints
   • Security requirements
   • Scaling needs
   • Resource constraints (CPU, memory)

Use AskUserQuestion if information is missing or unclear.

Example Questions:

- What programming language and version is your application using?
- What is the main entry point to run your application?
- Does your application expose any ports? If so, which ones?
- Do you need any system dependencies beyond the base language runtime?
- Does your application need a health check endpoint?

Stage 2: Framework/Library Documentation Lookup (if needed)

Objective: Research framework-specific containerization patterns and best practices.

When to Perform This Stage:

• User mentions a specific framework (Next.js, Django, FastAPI, Spring Boot, etc.)
• Application has complex build requirements
• Need guidance on framework-specific optimization

Research Process (strict fallback chain):

1. Read local references first (required):

   • references/security_best_practices.md
   • references/optimization_patterns.md
   • references/language_specific_guides.md

2. Use Context7 docs lookup when local references are insufficient (preferred external source):

   Use mcp__context7__resolve-library-id with the framework name
   Then use mcp__context7__query-docs with query:
   "docker deployment production build"
   

3. Use web search only if Context7 is unavailable or missing needed details:

   "<framework>" "<version>" dockerfile production deployment best practices
   

4. If external lookup is unavailable (offline/tooling limits):

   • Continue with local references and language templates in this file.
   • State assumptions explicitly in the output.
   • Mark the lookup limitation in the final report.

5. Extract only actionable data:

   • Recommended base image + version policy
   • Build optimization techniques
   • Required runtime environment variables
   • Production vs development differences
   • Security requirements specific to the framework

Stage 3: Generate Dockerfile

Objective: Create a production-ready, multi-stage Dockerfile following best practices.

Core Principles:

1. Multi-Stage Builds (REQUIRED for compiled languages, RECOMMENDED for all):

   • Separate build stage from runtime stage
   • Keep build tools out of final image
   • Copy only necessary artifacts
   • Results in 50-85% smaller images

2. Security Hardening (REQUIRED):

   • Use specific version tags (NEVER use :latest)
   • Run as non-root user (create dedicated user)
   • Use minimal base images (alpine, distroless)
   • No hardcoded secrets
   • Scan base images for vulnerabilities

3. Layer Optimization (REQUIRED):

   • Order instructions from least to most frequently changing
   • Copy dependency files before application code
   • Combine related RUN commands with &&
   • Clean up package manager caches in same layer
   • Leverage build cache effectively

4. Production Readiness (REQUIRED):

   • Add HEALTHCHECK for services
   • Use exec form for ENTRYPOINT/CMD
   • Set WORKDIR to absolute paths
   • Document exposed ports with EXPOSE

Language-Specific Templates:

Node.js Multi-Stage Dockerfile

Build-stage dependency rule: If the application has a build step (TypeScript, Vite, Webpack, etc.), install all dependencies in the builder stage (omit --only=production) and prune dev deps after the build. Using --only=production before a build step will cause npm run build to fail because dev tools are not installed.

# syntax=docker/dockerfile:1

# Build stage — installs all deps so build tools (tsc, vite, etc.) are available,
# then prunes dev deps so the production stage only ships what is needed at runtime.
FROM node:20-alpine AS builder
WORKDIR /app

# Copy dependency files for caching
COPY package*.json ./
# Install ALL dependencies (including devDependencies required by the build step)
RUN npm ci && \
    npm cache clean --force

# Copy application code
COPY . .

# Build application and prune dev dependencies
RUN npm run build && \
    npm prune --production

# Production stage
FROM node:20-alpine AS production
WORKDIR /app

# Set production environment
ENV NODE_ENV=production

# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Copy pruned node_modules and built application from builder
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app .

# Switch to non-root user
USER nodejs

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

# Start application
CMD ["node", "index.js"]

Simple app (no build step): If there is no compilation or bundling, install only production deps in the builder stage and copy source from the host context:

RUN npm ci --only=production && npm cache clean --force
...
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --chown=nodejs:nodejs . .

Python Multi-Stage Dockerfile

# syntax=docker/dockerfile:1

# Build stage
FROM python:3.12-slim AS builder
WORKDIR /app

# Install build dependencies
# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Copy dependency files
COPY requirements.txt .

# Install Python dependencies
RUN pip install --no-cache-dir --user -r requirements.txt

# Production stage
FROM python:3.12-slim AS production
WORKDIR /app

# Create non-root user
RUN useradd -m -u 1001 appuser

# Copy dependencies from builder
COPY --from=builder /root/.local /home/appuser/.local

# Copy application code
COPY --chown=appuser:appuser . .

# Update PATH and set Python production env vars
# PYTHONUNBUFFERED=1 ensures stdout/stderr are flushed immediately (essential for container logs)
# PYTHONDONTWRITEBYTECODE=1 prevents writing .pyc files to disk
ENV PATH=/home/appuser/.local/bin:$PATH \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

# Switch to non-root user
USER appuser

# Expose port
EXPOSE 8000

# Health check (adjust endpoint as needed)
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health').read()" || exit 1

# Start application
CMD ["python", "app.py"]

Go Multi-Stage Dockerfile

# syntax=docker/dockerfile:1

# Build stage
FROM golang:1.21-alpine AS builder
WORKDIR /app

# Copy go mod files
COPY go.mod go.sum ./
RUN go mod download

# Copy source code
COPY . .

# Build the application
RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" -o main .

# Production stage (using distroless for minimal image)
# gcr.io/distroless/static-debian12 IS a specific tag; hadolint DL3006 is a
# false positive for non-Docker-Hub registries.
# hadolint ignore=DL3006
FROM gcr.io/distroless/static-debian12 AS production
WORKDIR /

# Copy binary from builder
COPY --from=builder /app/main /main

# Expose port
EXPOSE 8080

# HEALTHCHECK is not supported in distroless images (no shell available)

# Switch to non-root user (distroless runs as nonroot by default)
USER nonroot:nonroot

# Start application
ENTRYPOINT ["/main"]

Java Multi-Stage Dockerfile

# syntax=docker/dockerfile:1

# Build stage
FROM eclipse-temurin:21-jdk-jammy AS builder
WORKDIR /app

# Copy Maven wrapper and pom.xml
COPY mvnw pom.xml ./
COPY .mvn .mvn

# Download dependencies (cached layer)
RUN ./mvnw dependency:go-offline

# Copy source code
COPY src ./src

# Build application
RUN ./mvnw clean package -DskipTests && \
    mv target/*.jar target/app.jar

# Production stage (using JRE instead of JDK)
FROM eclipse-temurin:21-jre-jammy AS production
WORKDIR /app

# Install healthcheck dependency and create non-root user
# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/* && \
    useradd -m -u 1001 appuser

# Copy JAR from builder
COPY --from=builder --chown=appuser:appuser /app/target/app.jar ./app.jar

# Switch to non-root user
USER appuser

# Expose port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
    CMD curl -f http://localhost:8080/actuator/health || exit 1

# Start application
ENTRYPOINT ["java", "-jar", "app.jar"]

Selection Logic:

• Node.js: Use for JavaScript/TypeScript applications
• Python: Use for Python applications (web, API, scripts)
• Go: Use for Go applications (excellent for minimal images)
• Java: Use for Spring Boot, Quarkus, or other Java frameworks
• Generic: Create custom Dockerfile for other languages

Always Include:

1. Syntax directive: # syntax=docker/dockerfile:1
2. Multi-stage build (build + production stages)
3. Non-root user creation and usage
4. HEALTHCHECK for services (if applicable)
5. Proper WORKDIR settings
6. EXPOSE for documented ports
7. Clean package manager caches
8. exec form for CMD/ENTRYPOINT

Stage 4: Generate .dockerignore

Objective: Create comprehensive .dockerignore to reduce build context and prevent secret leaks.

Always create .dockerignore with generated Dockerfile.

Standard .dockerignore Template:

# Git
.git
.gitignore
.gitattributes

# CI/CD
.github
.gitlab-ci.yml
.travis.yml
.circleci

# Documentation
README.md
CHANGELOG.md
CONTRIBUTING.md
LICENSE
*.md
docs/

# Docker
Dockerfile*
docker-compose*.yml
.dockerignore

# Environment
.env
.env.*
*.local

# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Dependencies (language-specific - add as needed)
node_modules/
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
venv/
.venv/
target/
*.class

# IDE
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

# Testing
coverage/
.coverage
*.cover
.pytest_cache/
.tox/
test-results/

# Build artifacts
dist/
build/
*.egg-info/

Customize based on language:

• Node.js: Add node_modules/, npm-debug.log, yarn-error.log
• Python: Add __pycache__/, *.pyc, .venv/, .pytest_cache/
• Go: Add vendor/, *.exe, *.test
• Java: Add target/, *.class, *.jar (except final artifact)

Stage 5: Validate with dockerfile-validator

Objective: Ensure generated Dockerfile follows best practices and has no unresolved critical findings.

REQUIRED: Always run validation after generation.

Primary path (preferred):

1. Invoke dockerfile-validator.
2. Capture findings by severity (error, warning, info).
3. Prioritize security and reproducibility findings first.

Fallback path (if skill invocation is unavailable):

1. Try local validator script directly:

   bash ../dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile
   

2. If that path is unavailable, run available tools directly:

   hadolint Dockerfile
   checkov -f Dockerfile --framework dockerfile
   

3. If one or more tools are unavailable, continue generation and report each skipped check in the final report.

Expected validator stages:

[1/4] Syntax Validation (hadolint)
[2/4] Security Scan (Checkov)
[3/4] Best Practices Validation
[4/4] Optimization Analysis

Stage 6: Validate-Iterate Loop (Explicit Requirements)

Objective: Apply deterministic fix loops with auditable iteration records.

Loop rules (required):

1. Run at least one validation pass.
2. If any error exists, apply fixes and re-run validation.
3. Continue until:
   • no error remains, or
   • iteration count reaches 3.
4. For warning, either fix it or mark it as intentional deviation with justification.
5. Never silently suppress a finding.

Iteration log format (required):

Common fixes:

• Add version tags to base images
• Add USER directive before CMD/ENTRYPOINT
• Add HEALTHCHECK for services
• Combine RUN commands where safe
• Clean package caches in same layer
• Replace ADD with COPY where archive/url behavior is not needed

Stage 7: Final Review and Audit Report

Objective: Deliver runnable artifacts plus an auditable report.

Deliverables (required):

1. Generated files:
   • Dockerfile (validated and optimized)
   • .dockerignore (comprehensive)
2. Validation summary:
   • tool path used (primary vs fallback)
   • findings by severity
   • final status after loop
3. Iteration log table from Stage 6.
4. Intentional deviation report (only when applicable).
5. Usage instructions.
6. Optimization metrics and next steps.

Intentional deviation report (required when any finding is not fixed):

Usage instructions template:

# Build image
docker build -t myapp:1.0 .

# Run container
docker run -p 3000:3000 myapp:1.0

# Probe health endpoint (if exposed)
curl http://localhost:3000/health

Optimization metrics (required):

## Optimization Metrics

| Metric | Estimate |
|--------|----------|
| Image Size | ~150MB (vs ~500MB without multi-stage, 70% reduction) |
| Build Cache | Layer caching enabled for dependencies |
| Security | Non-root user, minimal base image, no secrets |

Language-specific size estimates:

• Node.js: ~50-150MB with Alpine (vs ~1GB with full node image)
• Python: ~150-250MB with slim (vs ~900MB with full python image)
• Go: ~5-20MB with distroless/scratch (vs ~800MB with full golang image)
• Java: ~200-350MB with JRE (vs ~500MB+ with JDK)

Next steps (required):

## Next Steps

- [ ] Test the build locally: `docker build -t myapp:1.0 .`
- [ ] Run and verify the container works as expected
- [ ] Update CI/CD pipeline to use the new Dockerfile
- [ ] Consider BuildKit cache mounts for faster builds (see references/optimization_patterns.md)
- [ ] Set up automated vulnerability scanning with `docker scout` or `trivy`
- [ ] Push to registry and deploy

Generation Scripts (Optional Reference)

The scripts/ directory contains standalone bash scripts for manual Dockerfile generation outside of this skill:

• generate_nodejs.sh - CLI tool for Node.js Dockerfiles
• generate_python.sh - CLI tool for Python Dockerfiles
• generate_golang.sh - CLI tool for Go Dockerfiles
• generate_java.sh - CLI tool for Java Dockerfiles
• generate_dockerignore.sh - CLI tool for .dockerignore generation

Purpose: These scripts are reference implementations and manual tools for users who want to generate Dockerfiles via command line without using skill invocation. They demonstrate the same best practices embedded in this skill.

When using this skill: Codex generates Dockerfiles directly using the templates and patterns documented in this SKILL.md, rather than invoking these scripts. The templates in this document are the authoritative source.

Script usage example:

# Manual Dockerfile generation
cd devops-skills-plugin/skills/dockerfile-generator/scripts
./generate_nodejs.sh --version 20 --port 3000 --output Dockerfile

Node/Python entrypoint flags (script mode):

# Recommended for arguments containing spaces
./generate_nodejs.sh \
  --entry-cmd node \
  --entry-arg server.js \
  --entry-arg --message \
  --entry-arg "hello world"

Best Practices Reference

Security Best Practices

1. Use Specific Tags:

   # Bad
   FROM node:alpine
   
   # Good
   FROM node:20-alpine
   
   # Better (with digest for reproducibility)
   FROM node:20-alpine@sha256:abc123...
   

2. Run as Non-Root:

   # Create user
   RUN addgroup -g 1001 -S appgroup && \
       adduser -S appuser -u 1001 -G appgroup
   
   # Switch to user before CMD
   USER appuser
   

3. Use Minimal Base Images:

   • Alpine Linux (small, secure)
   • Distroless (no shell, minimal attack surface)
   • Specific runtime images (node:alpine vs node:latest)

4. Never Hardcode Secrets:

   # Bad
   ENV API_KEY=secret123
   
   # Good - use build secrets
   # docker build --secret id=api_key,src=.env
   RUN --mount=type=secret,id=api_key \
       API_KEY=$(cat /run/secrets/api_key) ./configure
   

Optimization Best Practices

1. Layer Caching:

   # Copy dependency files first
   COPY package.json package-lock.json ./
   RUN npm ci
   
   # Copy application code last
   COPY . .
   

2. Combine RUN Commands:

   # Bad (creates 3 layers)
   RUN apt-get update
   RUN apt-get install -y curl
   RUN rm -rf /var/lib/apt/lists/*
   
   # Good (creates 1 layer)
   RUN apt-get update && \
       apt-get install -y --no-install-recommends curl && \
       rm -rf /var/lib/apt/lists/*
   

3. Multi-Stage Builds:

   # Build stage - can be large
   FROM node:20 AS builder
   WORKDIR /app
   COPY . .
   RUN npm install && npm run build
   
   # Production stage - minimal
   FROM node:20-alpine
   COPY --from=builder /app/dist ./dist
   CMD ["node", "dist/index.js"]
   

Production Readiness

1. Health Checks:

   HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
       CMD curl -f http://localhost:3000/health || exit 1
   

2. Proper Signals:

   # Use exec form for proper signal handling
   CMD ["node", "server.js"]  # Good
   CMD node server.js         # Bad (no signal forwarding)
   

3. Metadata:

   LABEL maintainer="team@example.com" \
         version="1.0.0" \
         description="My application"
   

Common Patterns

Pattern 1: Node.js with Next.js

# syntax=docker/dockerfile:1
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nextjs -u 1001
COPY --from=builder --chown=nextjs:nodejs /app/.next ./.next
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
USER nextjs
EXPOSE 3000
CMD ["npm", "start"]

Pattern 2: Python with FastAPI

# syntax=docker/dockerfile:1
FROM python:3.12-slim AS builder
WORKDIR /app
# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y --no-install-recommends gcc && \
    rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
RUN useradd -m -u 1001 appuser
COPY --from=builder /root/.local /home/appuser/.local
COPY --chown=appuser:appuser . .
ENV PATH=/home/appuser/.local/bin:$PATH \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1
USER appuser
EXPOSE 8000
HEALTHCHECK CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Pattern 3: Go CLI Tool

# syntax=docker/dockerfile:1
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /bin/app

FROM scratch
COPY --from=builder /bin/app /app
ENTRYPOINT ["/app"]

Modern Docker Features (2025)

Multi-Platform Builds with BuildX

Use Case: Build images that work on both AMD64 and ARM64 architectures (e.g., x86 servers and Apple Silicon Macs).

Enable BuildX:

# BuildX is included in Docker Desktop by default
# For Linux, ensure BuildX is installed
docker buildx version

Create Multi-Platform Images:

# Build for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:latest \
  --push \
  .

# Build and load for current platform (testing)
docker buildx build \
  --platform linux/amd64 \
  -t myapp:latest \
  --load \
  .

Dockerfile Considerations:

# Most Dockerfiles work across platforms automatically
# Use platform-specific base images when needed
FROM --platform=$BUILDPLATFORM node:20-alpine AS builder

# Access build arguments for platform info
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "Building on $BUILDPLATFORM for $TARGETPLATFORM"

When to Use:

• Deploying to mixed infrastructure (x86 + ARM)
• Supporting Apple Silicon Macs in development
• Optimizing for AWS Graviton (ARM-based) instances
• Building cross-platform CLI tools

Software Bill of Materials (SBOM)

Use Case: Generate SBOM for supply chain security and compliance (increasingly required in 2025).

Generate SBOM During Build:

# Generate SBOM with BuildKit (Docker 24.0+)
docker buildx build \
  --sbom=true \
  -t myapp:latest \
  .

# SBOM is attached as attestation to the image
# View SBOM
docker buildx imagetools inspect myapp:latest --format "{{ json .SBOM }}"

Generate SBOM from Existing Image:

# Using Syft
syft myapp:latest -o json > sbom.json

# Using Docker Scout
docker scout sbom myapp:latest

SBOM Benefits:

• Vulnerability tracking across supply chain
• License compliance verification
• Dependency transparency
• Audit trail for security reviews
• Required for government/enterprise contracts

Integration with CI/CD:

# GitHub Actions example
- name: Build with SBOM
  run: |
    docker buildx build \
      --sbom=true \
      --provenance=true \
      -t myapp:latest \
      --push \
      .

BuildKit Cache Mounts (Advanced)

Use Case: Dramatically faster builds by persisting package manager caches across builds.

Already covered in detail in references/optimization_patterns.md.

Quick reference:

# syntax=docker/dockerfile:1

# NPM cache mount (30-50% faster builds)
RUN --mount=type=cache,target=/root/.npm \
    npm ci

# Go module cache
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

# Pip cache
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

Error Handling

Common Generation Issues

1. Missing dependency files:

   • Ensure package.json, requirements.txt, go.mod, pom.xml exist
   • Ask user to provide or generate template

2. Unknown framework:

   • Use local references first, then Context7, then web search
   • Fall back to generic template
   • Ask user for specific runtime/build requirements

3. Validation failures:

   • Apply fixes automatically
   • Iterate until clean
   • Document any suppressions

Integration with Other Skills

This skill works well in combination with:

• dockerfile-validator - Validates generated Dockerfiles (REQUIRED)
• k8s-yaml-generator - Generate Kubernetes deployments for the container
• helm-generator - Create Helm charts with the container image

Notes

• Always use multi-stage builds for compiled languages
• Always create non-root user for security
• Always generate .dockerignore to prevent secret leaks
• Always validate with dockerfile-validator (or explicit fallback checks)
• Iterate at least once if validation finds errors
• Use alpine or distroless base images when possible
• Pin all version tags (never use :latest)
• Clean up package manager caches in same layer
• Order Dockerfile instructions from least to most frequently changing
• Use BuildKit features for advanced optimization
• Test builds locally before committing
• Keep Dockerfiles simple and maintainable
• Document any non-obvious patterns with comments

Done Criteria

Mark the task done only when all items below are true:

• Dockerfile and .dockerignore are generated.
• Validation has been executed via dockerfile-validator or documented fallback commands.
• Validate-iterate loop evidence is present (iteration log with command path, counts, and fixes).
• No remaining validation error findings.
• Every remaining warning has either a fix or an intentional-deviation report row.
• Output includes optimization metrics and actionable next steps.

Sources

This skill is based on comprehensive research from authoritative sources:

Official Docker Documentation:

• Docker Best Practices
• Multi-stage Builds
• Dockerfile Reference

Security Guidelines:

• Dockerfile Best Practices 2025
• Docker Security Best Practices

Optimization Resources:

• Docker Multistage Builds Guide
• Building Optimized Docker Images

Dockerfile Validator

Validate Dockerfiles with deterministic stages, clear severity reporting, and explicit fallbacks when tools or network access are constrained.

Trigger Phrases

Use this skill when the user asks for tasks like:

• "validate this Dockerfile"
• "lint/check my Dockerfile"
• "security scan Dockerfile"
• "optimize Docker image size/build time"
• "review Dockerfile before merge"
• "find issues in Dockerfile.prod/Dockerfile.dev"

Use / Do Not Use

Use this skill for:

• Syntax and lint validation
• Security and secrets checks
• Best-practice and performance review
• Dockerfile hardening before CI/CD or production

Do not use this skill for:

• Generating a new Dockerfile from scratch (use dockerfile-generator)
• Running containers, debugging runtime behavior, or image registry operations

Local Files In This Skill

• Validator script: scripts/dockerfile-validate.sh
• References:
  • references/security_checklist.md
  • references/optimization_guide.md
  • references/docker_best_practices.md
• Example Dockerfiles: examples/*.Dockerfile

Deterministic Execution Flow (Required)

Run these steps in order. Do not skip steps unless a documented fallback branch applies.

1. Preflight and Path Setup

Assume repo root as working directory:

cd /path/to/repo
SKILL_DIR="devops-skills-plugin/skills/dockerfile-validator"
TARGET_DOCKERFILE="Dockerfile"   # replace when user provides a path

Validate inputs before running tools:

test -f "$SKILL_DIR/scripts/dockerfile-validate.sh"
test -f "$TARGET_DOCKERFILE"

If either check fails, stop and report the exact missing path.

2. Read the Target Dockerfile Explicitly

Use explicit file-read commands (not abstract "Read tool" wording):

sed -n '1,220p' "$TARGET_DOCKERFILE"

If needed for long files:

sed -n '220,440p' "$TARGET_DOCKERFILE"

3. Run Validation Script

Primary command:

bash "$SKILL_DIR/scripts/dockerfile-validate.sh" "$TARGET_DOCKERFILE"

Optional captured run for structured reporting:

bash "$SKILL_DIR/scripts/dockerfile-validate.sh" "$TARGET_DOCKERFILE" | tee /tmp/dockerfile-validator.out

4. Classify Findings by Severity (Standard)

Use this standard severity model:

• Critical
  • Hardcoded secrets/credentials
  • Explicit root runtime with high-risk context
  • High-impact security policy failures
• High
  • Checkov failures for container hardening
  • hadolint errors likely to cause insecure/unreliable builds
  • Missing or unsafe runtime-user posture (USER)
• Medium
  • :latest image tags, missing pinning, cache-cleanup misses
  • Build cache inefficiency and layered install anti-patterns
• Low
  • Style/info guidance and non-blocking optimization suggestions

5. No-Issue Fast Path (Required)

If validation has no actionable findings:

• Return a concise pass summary.
• Do not open reference files.
• Do not generate fix diffs.

Use fast path when all are true:

• Script reports overall pass.
• No security failures.
• No error/warning findings requiring user action.

6. Reference Loading Rules (Only When Findings Exist)

Only read references that match actual findings. Read each required file once.

Issue-to-reference mapping:

Explicit read commands:

sed -n '1,220p' "$SKILL_DIR/references/security_checklist.md"
sed -n '1,220p' "$SKILL_DIR/references/optimization_guide.md"
sed -n '1,220p' "$SKILL_DIR/references/docker_best_practices.md"

For targeted extraction:

rg -n "USER|secrets|EXPOSE|HEALTHCHECK" "$SKILL_DIR/references/security_checklist.md"
rg -n "multi-stage|cache|layer|dockerignore" "$SKILL_DIR/references/optimization_guide.md"
rg -n "FROM|COPY|ADD|WORKDIR|CMD|ENTRYPOINT|latest" "$SKILL_DIR/references/docker_best_practices.md"

7. Produce Standard Report Output

Use this template for every non-fast-path run:

## Dockerfile Validation Report
- Target: <path>
- Command: `bash <skill-script> <target>`
- Overall result: PASS | FAIL | PARTIAL (fallback)

### Critical
- <issue or `None`>

### High
- <issue or `None`>

### Medium
- <issue or `None`>

### Low
- <issue or `None`>

### Recommended Fixes
- <specific code-level fix per actionable issue>

### References Used
- <list only files actually read>

### Fallbacks Used
- `None` or exact fallback branch + reason

8. Offer Fix Application

After reporting:

• Ask whether to apply fixes.
• If user approves, patch the Dockerfile and rerun validation.

Fallback Behavior (Explicit)

When the primary script cannot complete, use deterministic fallback branches and report them.

Fallback A: Python/Tool Install Constraint

Condition:

• Script exits with tool-install failure (for example Python missing, package install blocked, or restricted environment).

Action:

1. Report primary failure and why.
2. Run manual minimum checks:

# Basic syntax signal (if Docker is available)
DOCKERFILE_DIR="$(dirname "$TARGET_DOCKERFILE")"
docker build --no-cache -f "$TARGET_DOCKERFILE" "$DOCKERFILE_DIR"

# High-value static checks
grep -nEi "^[[:space:]]*FROM[[:space:]]+.*:latest" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*(ENV|ARG)[[:space:]].*(password|secret|token|api[_-]?key)[[:space:]]*=" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*USER[[:space:]]+(root|0(:0)?)$" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*HEALTHCHECK[[:space:]]+" "$TARGET_DOCKERFILE" || true

3. Classify output with PARTIAL result and clearly label skipped checks.

Fallback B: hadolint Not Available but Docker Available

Use hadolint container image:

docker run --rm -i hadolint/hadolint < "$TARGET_DOCKERFILE"

Fallback C: No Docker, No hadolint/checkov

Run only manual regex-based checks (Fallback A step 2), clearly mark as PARTIAL, and state which scanners were skipped.

Quick Command Set

Validate one Dockerfile

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile

Validate alternate file

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile.prod

Validate skill examples

cd /path/to/repo/devops-skills-plugin/skills/dockerfile-validator
bash scripts/dockerfile-validate.sh examples/good-example.Dockerfile
bash scripts/dockerfile-validate.sh examples/security-issues.Dockerfile

Run regression checks (CI entrypoint)

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/test_validate.sh

Optional strict mode for CI environments that must enforce ShellCheck:

STRICT_SHELLCHECK=true bash devops-skills-plugin/skills/dockerfile-validator/scripts/test_validate.sh

Progressive Disclosure Rules

• Always read the target Dockerfile first.
• Do not read any reference files unless findings require them.
• Read only the matching reference file(s) from the issue-to-reference mapping.
• Do not reread the same reference unless new issue categories appear.

Done Criteria

Consider this skill execution complete only when all conditions below are satisfied:

• Trigger matched a Dockerfile validation/lint/security/optimization request.
• Target Dockerfile path was explicitly verified.
• Validation command (or explicit fallback) was executed.
• Findings were reported using severity buckets (Critical, High, Medium, Low).
• Reference usage matched issue categories and was explicitly listed.
• No-issue fast path skipped unnecessary reference reads.
• If fixes were applied, validation was rerun and final status reported.

Resources

• Script: scripts/dockerfile-validate.sh
• CI/regression entrypoint: scripts/test_validate.sh
• Security reference: references/security_checklist.md
• Optimization reference: references/optimization_guide.md
• Best-practices reference: references/docker_best_practices.md
• Examples: examples/good-example.Dockerfile, examples/bad-example.Dockerfile, examples/security-issues.Dockerfile, examples/python-optimized.Dockerfile, examples/golang-distroless.Dockerfile

Source Links

• Docker Build Best Practices
• Dockerfile Reference
• Checkov Dockerfile Scanning
• hadolint

Fluent Bit Config Generator

Trigger Guidance

Use this skill when the user asks for any of the following:

• Create or update a Fluent Bit config (fluent-bit.conf, parsers.conf)
• Build a log pipeline (INPUT -> FILTER -> OUTPUT)
• Configure Kubernetes logging with metadata enrichment
• Send logs/metrics to Elasticsearch, Loki, CloudWatch, S3, Kafka, OTLP, or Prometheus remote write
• Implement parser, multiline, lua, or stream processing behavior

Do not use this skill for pure validation-only requests; use fluentbit-validator in that case.

Execution Flow

Follow this sequence exactly. Do not skip stages.

Stage 1: Set Working Context and Preflight

Use one of these deterministic command patterns.

# Option A (recommended): run from this skill directory
cd /Users/akinozer/GolandProjects/cc-devops-skills/devops-skills-plugin/skills/fluentbit-generator
python3 scripts/generate_config.py --help

# Option B: run from any cwd with absolute paths
python3 /Users/akinozer/GolandProjects/cc-devops-skills/devops-skills-plugin/skills/fluentbit-generator/scripts/generate_config.py --help

Preflight checks:

• Confirm python3 is available.
• Confirm script help loads without errors.
• If using relative output paths, run from the intended target cwd.

Fallback:

• If python3 or script execution is unavailable, switch to manual generation flow (Stage 4) using examples/ templates.

Stage 2: Clarification Questionnaire (Explicit Template)

Collect these fields before generation.

Required questions:

1. Primary use case: kubernetes, application logs, syslog, http ingest, metrics, or custom?
2. Inputs: which sources and paths/ports (for example tail /var/log/containers/*.log)?
3. Outputs: destination plugin(s) and endpoint(s) (host, port, uri/topic/index/bucket)?
4. Reliability/security requirements: TLS on/off, retry expectations, buffering limits?
5. Environment context: cluster name, environment name, cloud region (if applicable)?

Optional but important:

1. Expected log format: json, regex, cri, docker, multiline stack traces?
2. Throughput profile: low/medium/high and acceptable latency?
3. Constraints: offline environment, missing binaries, read-only filesystem?

If any required answer is missing, ask focused follow-up questions before generating.

Stage 3: Decide Script vs Manual Generation

Use this decision table.

Supported script use cases:

• kubernetes-elasticsearch
• kubernetes-loki
• kubernetes-cloudwatch
• kubernetes-opentelemetry
• application-multiline
• syslog-forward
• file-tail-s3
• http-kafka
• multi-destination
• prometheus-metrics
• lua-filtering
• stream-processor
• custom

Always state the decision explicitly, including why the other path was not used.

Stage 4: Manual Generation (When Script Is Not the Best Fit)

1. Read the closest template in examples/ first.
2. Read examples/parsers.conf before defining new parsers.
3. Assemble config in this order:

• [SERVICE]
• [INPUT]
• [FILTER]
• [OUTPUT]
• parser definitions (if needed)

4. Reuse known-good sections from examples and only customize required parameters.
5. Keep tags and parser references consistent across sections.

Required local template selection:

• Kubernetes + Elasticsearch: examples/kubernetes-elasticsearch.conf
• Kubernetes + Loki: examples/kubernetes-loki.conf
• Kubernetes + CloudWatch: examples/cloudwatch.conf
• Kubernetes + OpenTelemetry: examples/kubernetes-opentelemetry.conf
• App multiline: examples/application-multiline.conf
• Syslog forward: examples/syslog-forward.conf
• File to S3: examples/file-tail-s3.conf
• HTTP to Kafka: examples/http-input-kafka.conf
• Multi destination: examples/multi-destination.conf
• Metrics: examples/prometheus-metrics.conf
• Lua filtering: examples/lua-filtering.conf
• Stream processor: examples/stream-processor.conf
• Parsers: examples/parsers.conf

Fallback:

• If no matching example exists, start from scripts/generate_config.py --use-case custom output shape and extend manually.

Stage 5: Script Generation Commands (Deterministic Examples)

Run from skill directory unless output path is absolute.

cd /Users/akinozer/GolandProjects/cc-devops-skills/devops-skills-plugin/skills/fluentbit-generator

# Kubernetes -> Elasticsearch
python3 scripts/generate_config.py \
  --use-case kubernetes-elasticsearch \
  --cluster-name prod-cluster \
  --environment production \
  --es-host elasticsearch.logging.svc \
  --es-port 9200 \
  --output output/fluent-bit.conf

# Kubernetes -> OpenTelemetry
python3 scripts/generate_config.py \
  --use-case kubernetes-opentelemetry \
  --cluster-name prod-cluster \
  --environment production \
  --otlp-endpoint otel-collector.observability.svc:4318 \
  --output output/fluent-bit-otlp.conf

# File tail -> S3
python3 scripts/generate_config.py \
  --use-case file-tail-s3 \
  --log-path /var/log/app/*.log \
  --s3-bucket my-logs-bucket \
  --s3-region us-east-1 \
  --output output/fluent-bit-s3.conf

Fallback:

• If a required option is unsupported by the script, document that gap and switch to Stage 4.

Stage 6: Plugin Documentation Lookup Fallback Chain

Use this strict order when plugin behavior or parameters are uncertain.

1. Context7 (first choice)

• Resolve library id for Fluent Bit docs.
• Query plugin-specific configuration details.

2. Official Fluent Bit docs (second choice)

• Use https://docs.fluentbit.io/manual and plugin-specific pages.
• Prefer official plugin reference sections over blogs.

3. Web search (last choice)

• Use only when Context7 and official docs are unavailable/incomplete.
• Prioritize sources that quote or link official docs.

When to stop escalating:

• Stop as soon as required parameters and one validated example are found.
• If all sources are unavailable, proceed with local examples/ and clearly mark assumptions.

Stage 7: Validation and Fallback Behavior

Primary validation path:

• Invoke fluentbit-validator after generation.

If validator is unavailable, run local fallback checks:

# Syntax/format smoke check when fluent-bit is installed
fluent-bit -c <generated-config> --dry-run

# Optional execution test
fluent-bit -c <generated-config>

If fluent-bit binary is missing:

• Perform static checks manually:
  • section headers are valid ([SERVICE], [INPUT], [FILTER], [OUTPUT])
  • required plugin keys exist
  • tag/match patterns align
  • parser names/files referenced correctly
  • no hardcoded credentials
• Report that runtime validation was skipped and why.

Stage 8: Response Contract

Always return:

1. Generation path used (script or manual) and reason.
2. Produced file(s) and key plugin choices.
3. Validation results (or explicit skip reason with fallback checks performed).
4. Assumptions, open risks, and what to customize next.

Done Criteria

This skill execution is complete only when all are true:

• Trigger fit was explicitly confirmed.
• Clarification questionnaire captured required fields or documented assumptions.
• Script-vs-manual decision was explicit and justified.
• Plugin lookup used deterministic chain: Context7 -> official docs -> web (as needed).
• Commands were provided with cwd-safe examples.
• Fallback behavior was applied for any missing tools/docs/network constraints.
• Validation was executed (or skipped with explicit reason and fallback static checks).
• Final response included generated artifacts, validation outcome, and next customization points.

Local Resources

• Script: scripts/generate_config.py
• Templates: examples/*.conf
• Parsers baseline: examples/parsers.conf
• Sample output directory: output/

Use these resources first before introducing new structure.

Fluent Bit Validator

Use this skill to run deterministic, repeatable validation for Fluent Bit classic-mode configs.

Trigger Phrases

Use this skill when prompts look like:

• "Validate this fluent-bit.conf before deploy"
• "Lint my Fluent Bit config and report issues"
• "Check tag routing and output matches in Fluent Bit"
• "Run security checks for Fluent Bit config"
• "Dry-run Fluent Bit config and tell me what failed"

Execution Model

Run steps in order. Do not skip Stage 0.

Stage 0: Precheck (Required)

Run from skill directory:

cd devops-skills-plugin/skills/fluentbit-validator

Check required and optional binaries:

command -v python3 >/dev/null 2>&1 && echo "python3: available" || echo "python3: missing"
command -v fluent-bit >/dev/null 2>&1 && echo "fluent-bit: available" || echo "fluent-bit: missing (dry-run will be skipped)"

Precheck protocol:

• If python3 is missing: stop script-based validation, report blocker, and switch to manual config review only.
• If fluent-bit is missing: continue static checks, skip dry-run, and record a Recommendation explaining skip reason and next step.

Stage 1: Static Validation (Required)

Default command:

python3 scripts/validate_config.py --file <config-file> --check all

Use targeted checks only when requested:

python3 scripts/validate_config.py --file <config-file> --check structure
python3 scripts/validate_config.py --file <config-file> --check sections
python3 scripts/validate_config.py --file <config-file> --check tags
python3 scripts/validate_config.py --file <config-file> --check security
python3 scripts/validate_config.py --file <config-file> --check performance
python3 scripts/validate_config.py --file <config-file> --check best-practices
python3 scripts/validate_config.py --file <config-file> --check dry-run

Strict CI gate (optional):

python3 scripts/validate_config.py --file <config-file> --check all --fail-on-warning

Stage 2: Dry-Run Handling (Conditional)

Dry-run command:

fluent-bit -c <config-file> --dry-run

Skip protocol:

• If fluent-bit is unavailable, do not fail static validation by default.
• Emit one explicit finding:
  • Recommendation: Dry-run skipped because fluent-bit binary is not available in PATH; run dry-run in CI or a Fluent Bit runtime image.
• If user explicitly requires dry-run as a release gate, run:

python3 scripts/validate_config.py --file <config-file> --check dry-run --require-dry-run

• In release-gate mode, missing fluent-bit must be reported as Error.

Stage 3: Reference Lookup (Optional)

Use only when plugin/parameter behavior is unclear after local checks.

Lookup order:

1. Context7 Fluent Bit docs.
2. Official docs at docs.fluentbit.io.
3. Broader web search limited to official/plugin sources.

Capture only:

• required fields,
• allowed values and defaults,
• version caveats relevant to the user config.

Stage 4: Report and Remediation (Required)

Use exactly these severity labels:

• Error
• Warning
• Recommendation

Do not introduce alternate labels (Info, Best Practice, Critical, etc.).

Report format:

Validation Report: <config-file>

Error:
- <blocking issue>

Warning:
- <non-blocking risk>

Recommendation:
- <improvement or skipped-step guidance>

Remediation flow:

1. Present findings with file/line context when available.
2. Ask for approval before changing user files.
3. Apply approved changes.
4. Re-run the same validation command(s).
5. Return delta: what changed, what remains, and final status.

No-issue fast path:

• If no findings exist, return a short pass summary and note whether dry-run was executed or skipped.

Fallback Matrix

Canonical Flows

Full validation flow

bash scripts/validate.sh --precheck
python3 scripts/validate_config.py --file tests/valid-basic.conf --check all

Constrained environment flow (fluent-bit unavailable)

bash scripts/validate.sh --precheck
python3 scripts/validate_config.py --file tests/invalid-security-issues.conf --check all --json

Expected outcome:

• Static findings still produced.
• Dry-run skipped and reported under Recommendation.

Done Criteria

Work is done only when all are true:

• Precheck was executed and binary availability was stated explicitly.
• Validation command(s) and scope are clear and reproducible.
• All findings use only Error, Warning, Recommendation.
• Dry-run path is explicit: executed or skipped with reason.
• Fallback behavior for tool/runtime constraints is documented in output.
• If fixes were applied, validation was re-run and post-fix status was reported.

Local Assets

• scripts/validate_config.py: main validator.
• scripts/validate.sh: wrapper and environment precheck helper.
• tests/*.conf: sample valid/invalid configs.
• tests/test_validate_config.py: regression coverage for parser and severity behavior.

GitHub Actions Generator

Generate production-ready GitHub Actions workflows and custom actions following current best practices, security standards, and naming conventions. All generated resources are automatically validated using the devops-skills:github-actions-validator skill.

Quick Reference

Trigger Decision Tree

Route every request through this decision tree before reading references or generating files:

1. If the user asks for .github/workflows/*.yml CI/CD automation, choose Workflow Generation.
2. If the user asks for action.yml or a reusable step package, choose Custom Action Generation.
3. If the user asks for workflow_call or shared pipelines across repositories, choose Reusable Workflow Generation.
4. If the request includes security-only scanning (dependency review, SBOM, CodeQL), stay on Workflow Generation with the security pattern.
5. If intent is ambiguous, ask one disambiguation question: "Do you want a workflow, a custom action, or a reusable workflow?"

Progressive Disclosure Route

Load only what is needed for the selected route, in this order:

If a required reference/template is unavailable, continue with the closest available reference and report the fallback explicitly in output.

Core Capabilities

1. Generate Workflows

Triggers: "Create a workflow for...", "Build a CI/CD pipeline..."

Process:

1. Understand requirements (triggers, runners, dependencies)
2. Define trust boundaries (internal branches vs fork PRs vs external triggers)
3. Set default permissions to read-only, then elevate only per job when required
4. Reference references/best-practices.md for patterns
5. Reference references/common-actions.md for action versions
6. Generate workflow with:
   • Semantic names, pinned actions (SHA), explicit permissions
   • Concurrency controls, caching, matrix strategies
   • Fork-safe PR handling (no secrets in untrusted contexts)
7. Validate with devops-skills:github-actions-validator skill
8. Fix issues and re-validate if needed

Minimal Example:

name: CI Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
        with:
          node-version: '24'
          cache: 'npm'
      - run: npm ci
      - run: npm test

Untrusted PR Guardrail (required for secret-using jobs):

jobs:
  deploy:
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository

2. Generate Custom Actions

Triggers: "Create a composite action...", "Build a Docker action...", "Create a JavaScript action..."

Types:

• Composite: Combine multiple steps → Fast startup
• Docker: Custom environment/tools → Isolated
• JavaScript: API access, complex logic → Fastest

Process:

1. Use templates from assets/templates/action/
2. Follow structure in references/custom-actions.md
3. Include branding, inputs/outputs, documentation
4. Validate with devops-skills:github-actions-validator skill

See references/custom-actions.md for:

• Action metadata and branding
• Directory structure patterns
• Versioning and release workflows

3. Generate Reusable Workflows

Triggers: "Create a reusable workflow...", "Make this workflow callable..."

Key Elements:

• workflow_call trigger with typed inputs
• Explicit secrets (avoid secrets: inherit)
• Explicit trusted-caller expectations (document org/repo boundaries)
• Outputs mapped from job outputs
• Minimal permissions

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      deploy-token:
        required: false
    outputs:
      result:
        value: ${{ jobs.build.outputs.result }}

When secrets are required, pass only the exact secret names needed and prefer environment protection rules for deployment stages.

See references/advanced-triggers.md for complete patterns.

4. Generate Security Workflows

Triggers: "Add security scanning...", "Add dependency review...", "Generate SBOM..."

Components:

• Dependency Review: actions/dependency-review-action@v4
• SBOM Attestations: actions/attest-sbom@v2
• CodeQL Analysis: github/codeql-action

Permission Model: Use a read-only workflow-level baseline, then elevate only in the security job that requires write scopes.

permissions:
  contents: read

jobs:
  security-scan:
    permissions:
      contents: read
      security-events: write  # For CodeQL
      id-token: write         # For attestations
      attestations: write     # For attestations

See references/best-practices.md section on security.

5. Modern Features

Triggers: "Add job summaries...", "Use environments...", "Run in container..."

See references/modern-features.md for:

• Job summaries ($GITHUB_STEP_SUMMARY)
• Deployment environments with approvals
• Container jobs with services
• Workflow annotations

6. Third-Party Action Documentation and Citation

When using third-party actions (any uses: entry not in the same repository):

1. Search for documentation:

   "[owner/repo] [version] github action documentation"
   

2. Or use Context7 MCP:

   • mcp__context7__resolve-library-id to find action
   • mcp__context7__query-docs for documentation

3. Pin to SHA with version comment:

   - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
   

4. Cite source and version in the response:

   • Action source (repository URL)
   • Version source (release/tag/changelog URL)
   • Selected commit SHA and human-readable version
   • Access date for the source used

See references/common-actions.md for pre-verified action versions.

Validation Workflow

CRITICAL: Every generated resource MUST be validated.

1. Generate workflow/action file
2. Invoke devops-skills:github-actions-validator skill
3. If errors: fix and re-validate
4. If success: present with usage instructions

Skip validation only for:

• Partial code snippets
• Documentation examples
• User explicitly requests skip

Fallback Behavior (Tooling and Environment Constraints)

If required tooling or network access is unavailable, use this deterministic fallback order:

1. If devops-skills:github-actions-validator is unavailable, run local fallback checks:
   • actionlint (if installed)
   • yamllint (if installed)
   • manual YAML/schema review with a clear "not tool-validated" note
2. If Context7 or internet access is unavailable:
   • use references/common-actions.md for known action versions
   • state that external version verification could not be completed
3. If a template path is missing:
   • generate from the closest template pattern in assets/templates/
   • document which template was substituted

Fallback usage must always be reported in the final output.

Mandatory Standards

All generated resources must follow:

See references/best-practices.md for complete guidelines.

Resources

Reference Documents

Templates

Common Patterns

Matrix Testing

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20, 22]
  fail-fast: false

Conditional Deployment

deploy:
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'

Artifact Sharing

# Upload
- uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1
  with:
    name: build-${{ github.sha }}
    path: dist/

# Download (in dependent job)
- uses: actions/download-artifact@c850b930e6ba138125429b7e5c93fc707a7f8427 # v4.1.4
  with:
    name: build-${{ github.sha }}

Third-Party Action Citation Block

Third-party action citations:
- actions/checkout: https://github.com/actions/checkout (version: v6.0.2, sha: de0fac2e4500dabe0009e67214ff5f5447ce83dd, accessed: 2026-02-28)

Done Criteria

The task is complete only when all checks below pass:

1. The request route was selected using the trigger decision tree.
2. Only the minimum required references/templates were loaded first.
3. Every third-party action is pinned to a commit SHA and has source/version citation.
4. Validation was run, or a skip exception/fallback path was explicitly documented.
5. Output includes assumptions, security-sensitive decisions (permissions/secrets), and generated file paths.

Workflow Summary

1. Route the request using the trigger decision tree
2. Load the minimum references/templates for that route
3. Generate using mandatory security and naming standards
4. Cite and pin third-party actions (source, version, SHA)
5. Validate with devops-skills:github-actions-validator (or documented fallback)
6. Fix and re-validate until clean
7. Present validated output with citations, assumptions, and file paths

GitHub Actions Validator

Overview

Validate and test GitHub Actions workflows, custom actions, and public actions using industry-standard tools (actionlint and act). This skill provides comprehensive validation including syntax checking, static analysis, local workflow execution testing, and action verification with version-aware documentation lookup.

Trigger Phrases

Use this skill when the request includes phrases like:

• "validate this GitHub Actions workflow"
• "check my .github/workflows/*.yml file"
• "debug actionlint errors"
• "test this workflow locally with act"
• "verify GitHub Action versions or deprecations"

When to Use This Skill

Use this skill when:

• Validating workflow files: Checking .github/workflows/*.yml for syntax errors and best practices
• Testing workflows locally: Running workflows with act before pushing to GitHub
• Debugging workflow failures: Identifying issues in workflow configuration
• Validating custom actions: Checking composite, Docker, or JavaScript actions
• Verifying public actions: Validating usage of actions from GitHub Marketplace
• Pre-commit validation: Ensuring workflows are valid before committing

Required Execution Flow

Every validation run should follow these steps in order.

Step 1: Set Skill Path and Run Validation

Run commands from the repository root that contains .github/workflows/.

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" <workflow-file-or-directory>

Step 2: Map Each Error to a Reference

For each actionlint/act error, consult the mapping table below, then extract the matching fix pattern.

Step 3: Apply Minimal-Quote Policy

For each issue:

1. Include the exact error line from tool output.
2. Quote only the smallest useful snippet from references/ (prefer <=8 lines).
3. Paraphrase the rest and cite the source file/section.
4. Show corrected workflow code.

Step 4: Handle Unmapped Errors Explicitly

If an error does not match any mapping:

1. Label it as UNMAPPED.
2. Capture exact tool output, workflow file, and line number (if available).
3. Check references/common_errors.md general sections first.
4. If still unresolved, search official docs with the exact error string.
5. Mark the fix as provisional until post-fix rerun passes.

Step 5: Verify Public Action Versions

For each uses: owner/action@version:

1. Check references/action_versions.md.
2. For unknown actions, verify against official docs.
3. Confirm required inputs and deprecations.

Offline mode behavior:

• If network/doc lookup is unavailable, rely on references/action_versions.md only.
• Mark unknown actions as UNVERIFIED-OFFLINE.
• Do not claim "latest" version without an online verification pass.

Step 6: Mandatory Post-Fix Rerun

After applying fixes, rerun validation before finalizing:

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" <workflow-file-or-directory>

Step 7: Provide Final Summary

Final output should include:

• Issues found and fixes applied
• Any UNMAPPED or UNVERIFIED-OFFLINE items
• Post-fix rerun command and result
• Remaining warnings/risk notes

Error Type to Reference File Mapping

Example: Complete Error Handling Workflow

User's workflow has this error:

runs-on: ubuntu-lastest

Step 1 - Script output:

label "ubuntu-lastest" is unknown

Step 2 - Read references/runners.md or references/common_errors.md: Find the "Invalid Runner Label" section.

Step 3 - Quote the fix to user:

Error: label "ubuntu-lastest" is unknown

Cause: Typo in runner label (from references/common_errors.md):

# Bad
runs-on: ubuntu-lastest  # Typo

Fix (from references/common_errors.md):

# Good
runs-on: ubuntu-latest

Valid runner labels (from references/runners.md):

• ubuntu-latest, ubuntu-24.04, ubuntu-22.04
• windows-latest, windows-2025, windows-2022
• macos-latest, macos-15, macos-14

Step 4 - Provide corrected code:

runs-on: ubuntu-latest

Quick Start

Set once per shell session:

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"

Initial Setup

bash "$SKILL_DIR/scripts/install_tools.sh"

This installs act (local workflow execution) and actionlint (static analysis) to scripts/.tools/.

Basic Validation

# Validate a single workflow
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

# Validate all workflows
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/

# Lint-only (fastest)
bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/ci.yml

# Test-only with act (requires Docker)
bash "$SKILL_DIR/scripts/validate_workflow.sh" --test-only .github/workflows/

Core Validation Workflow

1. Static Analysis with actionlint

Start with static analysis to catch syntax errors and common issues:

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/ci.yml

What actionlint checks: YAML syntax, schema compliance, expression syntax, runner labels, action inputs/outputs, job dependencies, CRON syntax, glob patterns, shell scripts, security vulnerabilities.

2. Local Testing with act

After passing static analysis, test workflow execution:

bash "$SKILL_DIR/scripts/validate_workflow.sh" --test-only .github/workflows/

Note: act has limitations - see references/act_usage.md.

3. Full Validation

bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

Default behavior if tools/runtime are unavailable:

• If act is missing, full validation falls back to actionlint-only.
• If Docker is unavailable, full validation skips act and continues with actionlint.
• --check-versions works in offline/local mode using references/action_versions.md.

Validating Resource Types

Workflows

# Single workflow
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/ci.yml

# All workflows
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/

Key validation points: triggers, job configurations, runner labels, environment variables, secrets, conditionals, matrix strategies.

Custom Local Actions

Create a test workflow that uses the custom action, then validate:

bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/test-custom-action.yml

Public Actions

When workflows use public actions (e.g., actions/checkout@v6):

1. Check references/action_versions.md first
2. Use official docs (or web search) for unknown actions
3. Verify required inputs and version
4. Check for deprecation warnings
5. Run validation script

If offline:

• Mark unknown versions as UNVERIFIED-OFFLINE
• Avoid "latest/current" claims until online verification is possible

Search format: "[action-name] [version] github action documentation"

Reference File Consultation Guide

Mandatory Reference Consultation

Script Output to Reference Mapping

Reference Files Summary

Troubleshooting

Debug Mode

actionlint -verbose .github/workflows/ci.yml  # Verbose actionlint
act -v                                         # Verbose act
act -n                                         # Dry-run (no execution)

Best Practices

1. Always validate locally first - Catch errors before pushing
2. Use actionlint in CI/CD - Automate validation in pipelines
3. Pin action versions - Use @v6 not @main for stability; SHA pinning for security
4. Keep tools updated - Regularly update actionlint and act
5. Use official docs for unknown actions - Verify usage and versions
6. Check version compatibility - See references/action_versions.md
7. Enable shellcheck - Catch shell script issues early
8. Review security warnings - Address script injection issues

Limitations

• act limitations: Not all GitHub Actions features work locally
• Docker requirement: act requires Docker to be running
• Network actions: Some GitHub API actions may fail locally
• Private actions: Cannot validate without access
• Runtime behavior: Static analysis cannot catch all issues
• File location: act can only validate workflows in .github/workflows/ directory; files outside (like examples/) can only be validated with actionlint

Quick Examples

Example 1: Pre-commit Validation

SKILL_DIR="devops-skills-plugin/skills/github-actions-validator"
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/
git add .github/workflows/ && git commit -m "Update workflows"

Example 2: Debug Failing Workflow

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only .github/workflows/failing.yml
# Fix issues
bash "$SKILL_DIR/scripts/validate_workflow.sh" .github/workflows/failing.yml

Complete Worked Example: Multi-Error Workflow

This example demonstrates the full assistant workflow for handling multiple errors.

User's Problematic Workflow

name: Broken CI
on:
  schedule:
    - cron: '0 0 * * 8'  # ERROR 1
jobs:
  build:
    runs-on: ubuntu-lastest  # ERROR 2
    steps:
      - uses: actions/checkout@v3  # ERROR 3 (outdated)
      - run: echo ${{ github.event.issue.title }}  # ERROR 4 (security)
  deploy:
    needs: biuld  # ERROR 5 (typo)
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

Step 1: Run Validation

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only workflow.yml

Output:

[ERROR] invalid CRON format "0 0 * * 8"
[ERROR] label "ubuntu-lastest" is unknown
[WARN] "github.event.issue.title" is potentially untrusted
[ERROR] job "deploy" needs job "biuld" which does not exist

Step 2-3: Consult References and Quote Fixes

Error 1: Invalid CRON Expression

From references/common_errors.md - Schedule Errors:

Cause: Day of week 8 doesn't exist (valid: 0-6, where 0 = Sunday)

# Bad
schedule:
  - cron: '0 0 * * 8'  # Day 8 doesn't exist

# Good
schedule:
  - cron: '0 0 * * 0'  # Sunday

CRON format: minute hour day month weekday

• Weekday: 0-6 (0 = Sunday)

Fix: Change 8 to 0 (Sunday) or 1-6 for Monday-Saturday.

Error 2: Invalid Runner Label

From references/common_errors.md - Job Configuration Errors and references/runners.md:

Cause: Typo in runner label

# Bad
runs-on: ubuntu-lastest  # Typo

# Good
runs-on: ubuntu-latest

Valid labels (from references/runners.md):

• ubuntu-latest (Ubuntu 24.04)
• ubuntu-24.04, ubuntu-22.04
• macos-latest (macOS 15)
• windows-latest (Windows Server 2022)

Fix: Change ubuntu-lastest to ubuntu-latest.

Error 3: Outdated Action Version

From references/action_versions.md:

Action	Current Version	Minimum Supported
actions/checkout	v6	v4

SHA Pinning Best Practice:

# Recommended: SHA pinning with version comment
- uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0

Fix: Update from @v3 to @v6 (or SHA-pinned version).

Error 4: Security Vulnerability (Script Injection)

From references/common_errors.md - Expression Errors:

Warning: Potential script injection via untrusted input

# Bad - vulnerable to injection
run: echo ${{ github.event.issue.title }}

# Good - use environment variables
env:
  TITLE: ${{ github.event.issue.title }}
run: echo "$TITLE"

Why: Untrusted input (issue titles, PR bodies, commit messages) can contain malicious commands. Using environment variables sanitizes the input.

Fix: Pass untrusted input through environment variable.

Error 5: Undefined Job Dependency

From references/common_errors.md - Job Configuration Errors:

Error: Job 'deploy' depends on job 'biuld' which does not exist

# Bad
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: biuld  # Typo

# Good
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: build

Fix: Change biuld to build.

Step 4: Provide Corrected Workflow

name: Fixed CI
on:
  schedule:
    - cron: '0 0 * * 0'  # Fixed: Sunday (0-6 valid)
jobs:
  build:
    runs-on: ubuntu-latest  # Fixed: typo corrected
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0 - Fixed: updated version
      - name: Process issue
        env:
          TITLE: ${{ github.event.issue.title }}  # Fixed: use env var
        run: echo "$TITLE"
  deploy:
    needs: build  # Fixed: typo corrected
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

Step 5: Mandatory Rerun

bash "$SKILL_DIR/scripts/validate_workflow.sh" --lint-only workflow.yml

Expected rerun result:

• No previous errors reproduced
• Remaining warnings, if any, are documented explicitly

Step 6: Summary

Recommendations:

• Run bash "$SKILL_DIR/scripts/validate_workflow.sh" --check-versions regularly
• Use SHA pinning for all actions in production workflows
• Always pass untrusted input through environment variables

Done Criteria

Validation work is complete when all are true:

• Trigger matched and correct validation mode selected.
• Each mapped error includes source reference and minimal quote.
• Each unmapped error is labeled UNMAPPED with exact output captured.
• Public action versions are verified, or marked UNVERIFIED-OFFLINE.
• Post-fix rerun executed and result reported.

Summary

1. Setup: Install tools with install_tools.sh
2. Validate: Run validate_workflow.sh on workflow files
3. Fix: Address issues using reference documentation
4. Rerun: Verify fixes with a mandatory post-fix validation run
5. Search: Use official docs to verify unknown actions
6. Commit: Push validated workflows with confidence

For detailed information, consult the appropriate reference file in references/.

GitLab CI/CD Pipeline Generator

Overview

Generate production-ready GitLab CI/CD pipeline configurations following current best practices, security standards, and naming conventions. All generated resources are automatically validated using the devops-skills:gitlab-ci-validator skill to ensure syntax correctness and compliance with best practices.

Trigger Phrases

Use this skill when the user asks for GitLab CI/CD generation requests such as:

• "Create a .gitlab-ci.yml for..."
• "Build a GitLab pipeline for Node/Python/Java..."
• "Add Docker build and deploy jobs in GitLab CI"
• "Set up GitLab parent-child or multi-project pipelines"
• "Include SAST/dependency scanning templates in GitLab CI"

Execution Model

Follow this deterministic flow in order:

1. Classify request complexity (targeted, lightweight, or full).
2. Load only the required reference tier for that complexity.
3. Output the matching response profile for the selected mode.
4. For complete pipeline generation, start from the closest template and customize.
5. Validate complete pipelines with strict Critical/High gates.
6. Present output with validation status and template/version notes.

If tooling is unavailable, use the documented fallback branch and report it explicitly.

Mode Routing (Quick Decision)

When uncertain on a complete-generation request, route to Full mode.

MANDATORY PRE-GENERATION STEPS

CRITICAL: Before generating any complete GitLab CI/CD pipeline, complete these steps.

Step 1: Classify Complexity (REQUIRED)

When uncertain on a complete-generation request, default to Full mode.

Step 2: Load References by Tier (REQUIRED)

Use an open/read action to load references based on the selected mode.

Targeted mode (review/Q&A/snippet/focused fix):

• Load only directly relevant references/templates for the scoped request.
• Do not enforce Full-generation Tier 1/Tier 2 checklist items.

Tier 1 (Required for complete pipeline generation in Lightweight and Full modes):

1. references/best-practices.md - baseline security, performance, naming
2. references/common-patterns.md - starting pattern selection
3. Matching template from assets/templates/:
   • Docker pipelines -> assets/templates/docker-build.yml
   • Kubernetes deployments -> assets/templates/kubernetes-deploy.yml
   • Multi-project pipelines -> assets/templates/multi-project.yml
   • Basic pipelines -> assets/templates/basic-pipeline.yml

Tier 2 (Required for Full mode; optional for Lightweight mode):

1. references/gitlab-ci-reference.md - keyword/syntax edge cases
2. references/security-guidelines.md - security-sensitive controls

Tier 3 (Conditional external docs lookup):

• Use only when local references do not cover requested features or version-specific behavior.
• Follow the lookup flow in "Handling GitLab CI/CD Documentation Lookup."

If a required local reference or template is unavailable:

• Report the exact missing path.
• Continue with available references and mark assumptions explicitly.
• Do not claim production-ready confidence until missing critical inputs are resolved.

Step 3: Confirm Understanding (EXPLICIT OUTPUT REQUIRED)

Lightweight Confirmation Mode

Use for simple requests only.

Required format:

## Reference Analysis Complete (Lightweight)

**Pattern:** [Pattern name] from common-patterns.md
**Template:** [Template file]
**Key standards to enforce:**
- [2-3 concrete standards]

Example:

## Reference Analysis Complete (Lightweight)

**Pattern:** Basic Build-Test-Deploy from common-patterns.md
**Template:** assets/templates/basic-pipeline.yml
**Key standards to enforce:**
- Pin runtime image versions (no `:latest`)
- Add explicit job timeouts
- Use `rules` instead of deprecated `only`/`except`

Full Confirmation Mode

Use for complex or security-sensitive requests.

Required format:

## Reference Analysis Complete (Full)

**Pipeline Pattern Identified:** [Pattern name] from common-patterns.md
- [Brief description of why this pattern fits]

**Best Practices to Apply:**
- [List 3-5 key best practices relevant to this pipeline]

**Security Guidelines:**
- [List security measures to implement]

**Template Foundation:** [Template file name]
- [What will be customized from this template]

Example:

## Reference Analysis Complete (Full)

**Pipeline Pattern Identified:** Docker Build + Kubernetes Deployment from common-patterns.md
- User needs containerized deployment to K8s clusters with staging/production environments

**Best Practices to Apply:**
- Pin all Docker images to specific versions (not `:latest`)
- Use caching for pip dependencies
- Implement DAG optimization with `needs` keyword
- Set explicit timeout on all jobs (15-20 minutes)
- Use `resource_group` for deployment jobs

**Security Guidelines:**
- Use masked CI/CD variables for secrets (KUBE_CONTEXT, registry credentials)
- Include container scanning with Trivy
- Never expose secrets in logs

**Template Foundation:** assets/templates/docker-build.yml + assets/templates/kubernetes-deploy.yml
- Combine Docker build pattern with K8s kubectl deployment
- Add Python-specific test jobs

Skipping confirmation is not allowed for complete pipeline generation.

Core Capabilities

1. Generate Basic CI/CD Pipelines

Create complete, production-ready .gitlab-ci.yml files with proper structure, security best practices, and efficient CI/CD patterns.

When to use:

• User requests: "Create a GitLab pipeline for...", "Build a CI/CD pipeline...", "Generate GitLab CI config..."
• Scenarios: CI/CD pipelines, automated testing, build automation, deployment pipelines

Process:

1. Understand the user's requirements (what needs to be automated)
2. Identify stages, jobs, dependencies, and artifacts
3. Use assets/templates/basic-pipeline.yml as structural foundation
4. Reference references/best-practices.md for implementation patterns
5. Reference references/common-patterns.md for standard pipeline patterns
6. Generate the pipeline following these principles:
   • Use semantic stage and job names
   • Pin Docker images to specific versions (not :latest)
   • Implement proper secrets management with masked variables
   • Use caching for dependencies to improve performance
   • Implement proper artifact handling with expiration
   • Use needs keyword for DAG optimization when appropriate
   • Add proper error handling with retry and allow_failure
   • Use rules instead of deprecated only/except
   • Set explicit timeout for all jobs (10-30 minutes typically)
   • Add meaningful job descriptions in comments
7. ALWAYS validate the generated pipeline using the devops-skills:gitlab-ci-validator skill
8. If validation fails, fix the issues and re-validate

Example structure:

# Basic CI/CD Pipeline
# Builds, tests, and deploys the application

stages:
  - build
  - test
  - deploy

# Global variables
variables:
  NODE_VERSION: "20"
  DOCKER_DRIVER: overlay2

# Default settings for all jobs
default:
  image: node:20-alpine
  timeout: 20 minutes  # Default timeout for all jobs
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  before_script:
    - echo "Starting job ${CI_JOB_NAME}"
  tags:
    - docker
  interruptible: true

# Build stage - Compiles the application
build-application:
  stage: build
  timeout: 15 minutes
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  rules:
    - changes:
        - src/**/*
        - package*.json
      when: always
    - when: on_success

# Test stage
test-unit:
  stage: test
  needs: [build-application]
  script:
    - npm run test:unit
  coverage: '/Coverage: \d+\.\d+%/'
  artifacts:
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

test-lint:
  stage: test
  needs: []  # Can run immediately
  script:
    - npm run lint
  allow_failure: true

# Deploy stage
deploy-staging:
  stage: deploy
  needs: [build-application, test-unit]
  script:
    - npm run deploy:staging
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
  when: manual

deploy-production:
  stage: deploy
  needs: [build-application, test-unit]
  script:
    - npm run deploy:production
  environment:
    name: production
    url: https://example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  when: manual
  resource_group: production

2. Generate Docker Build Pipelines

Create pipelines for building, testing, and pushing Docker images to container registries.

When to use:

• User requests: "Create a Docker build pipeline...", "Build and push Docker images..."
• Scenarios: Container builds, multi-stage Docker builds, registry pushes

Process:

1. Understand the Docker build requirements (base images, registries, tags)
2. Use assets/templates/docker-build.yml as foundation
3. Implement Docker-in-Docker or Kaniko for builds
4. Configure registry authentication
5. Implement image tagging strategy
6. Add security scanning if needed
7. ALWAYS validate using devops-skills:gitlab-ci-validator skill

Example:

stages:
  - build
  - scan
  - push

variables:
  DOCKER_DRIVER: overlay2
  IMAGE_NAME: $CI_REGISTRY_IMAGE
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA

# Build Docker image
docker-build:
  stage: build
  image: docker:24-dind
  timeout: 20 minutes
  services:
    - docker:24-dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build
        --cache-from $IMAGE_NAME:latest
        --tag $IMAGE_NAME:$IMAGE_TAG
        --tag $IMAGE_NAME:latest
        .
    - docker push $IMAGE_NAME:$IMAGE_TAG
    - docker push $IMAGE_NAME:latest
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  retry:
    max: 2
    when:
      - runner_system_failure

# Scan for vulnerabilities
container-scan:
  stage: scan
  image: aquasec/trivy:0.49.0
  timeout: 15 minutes
  script:
    - trivy image --exit-code 0 --severity HIGH,CRITICAL $IMAGE_NAME:$IMAGE_TAG
  needs: [docker-build]
  allow_failure: true
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

3. Generate Kubernetes Deployment Pipelines

Create pipelines that deploy applications to Kubernetes clusters.

When to use:

• User requests: "Deploy to Kubernetes...", "Create K8s deployment pipeline..."
• Scenarios: Kubernetes deployments, Helm deployments, kubectl operations

Process:

1. Identify the Kubernetes deployment method (kubectl, Helm, Kustomize)
2. Use assets/templates/kubernetes-deploy.yml as foundation
3. Configure cluster authentication (service accounts, kubeconfig)
4. Implement proper environment management
5. Add rollback capabilities
6. ALWAYS validate using devops-skills:gitlab-ci-validator skill

Example:

stages:
  - build
  - deploy

# Kubernetes deployment job
deploy-k8s:
  stage: deploy
  image: bitnami/kubectl:1.29
  timeout: 10 minutes
  before_script:
    - kubectl config use-context $KUBE_CONTEXT
  script:
    - kubectl set image deployment/myapp myapp=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA -n $KUBE_NAMESPACE
    - kubectl rollout status deployment/myapp -n $KUBE_NAMESPACE --timeout=5m
  environment:
    name: production
    url: https://example.com
    kubernetes:
      namespace: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
  resource_group: k8s-production
  retry:
    max: 2
    when:
      - runner_system_failure

4. Generate Multi-Project Pipelines

Create pipelines that trigger other projects or use parent-child pipeline patterns.

When to use:

• User requests: "Create multi-project pipeline...", "Trigger other pipelines..."
• Scenarios: Monorepos, microservices, orchestration pipelines

Process:

1. Identify the pipeline orchestration needs
2. Use assets/templates/multi-project.yml or parent-child templates
3. Configure proper artifact passing
4. Implement parallel execution where appropriate
5. ALWAYS validate using devops-skills:gitlab-ci-validator skill

Example (Parent-Child):

# Parent pipeline
stages:
  - trigger

generate-child-pipeline:
  stage: trigger
  script:
    - echo "Generating child pipeline config"
    - |
      cat > child-pipeline.yml <<EOF
      stages:
        - build

      child-job:
        stage: build
        script:
          - echo "Running child job"
      EOF
  artifacts:
    paths:
      - child-pipeline.yml

trigger-child:
  stage: trigger
  trigger:
    include:
      - artifact: child-pipeline.yml
        job: generate-child-pipeline
    strategy: depend
  needs: [generate-child-pipeline]

5. Generate Template-Based Configurations

Create reusable templates using extends, YAML anchors, and includes.

When to use:

• User requests: "Create reusable templates...", "Build modular pipeline config..."
• Scenarios: Template libraries, DRY configurations, shared CI/CD logic

Process:

1. Identify common patterns to extract
2. Create hidden jobs (prefixed with .)
3. Use extends keyword for inheritance
4. Organize into separate files with include
5. ALWAYS validate using devops-skills:gitlab-ci-validator skill

Example:

# Hidden template jobs (include timeout in templates)
.node-template:
  image: node:20-alpine
  timeout: 15 minutes  # Default timeout for jobs using this template
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  before_script:
    - npm ci
  interruptible: true

.deploy-template:
  timeout: 10 minutes  # Deploy jobs should have explicit timeout
  before_script:
    - echo "Deploying to ${ENVIRONMENT}"
  after_script:
    - echo "Deployment complete"
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
  interruptible: false  # Deploys should not be interrupted

# Actual jobs using templates
build:
  extends: .node-template
  stage: build
  script:
    - npm run build

deploy-staging:
  extends: .deploy-template
  stage: deploy
  variables:
    ENVIRONMENT: staging
  script:
    - ./deploy.sh staging
  resource_group: staging

6. Handling GitLab CI/CD Documentation Lookup

Use this flow only when local references do not cover requested features or version-sensitive behavior.

Detection:

• User mentions specific GitLab features (e.g., "Auto DevOps", "SAST", "dependency scanning")
• User requests integration with GitLab templates
• Pipeline requires specific GitLab runner features

Process:

1. Identify the feature:

   • Extract the GitLab feature or template name
   • Determine if version-specific information is needed

2. Check local references first (Tier 1/Tier 2):

   • references/common-patterns.md
   • references/gitlab-ci-reference.md
   • references/security-guidelines.md

3. Use Context7 first when external lookup is needed:

   • Resolve library: mcp__context7__resolve-library-id
   • Query docs: mcp__context7__query-docs
   • Prefer GitLab official/library docs over secondary sources

4. Fallback to web search when Context7 is unavailable or insufficient:

   • Use web.search_query
   • Query pattern: "GitLab CI/CD [feature] documentation"
   • Prefer results from docs.gitlab.com

5. Open and extract from specific docs pages when needed:

   • Use web.open for selected documentation pages
   • Capture required syntax, variables, and version constraints

6. Analyze discovered documentation for:

   • Current recommended approach
   • Required variables and configuration
   • Template include syntax
   • Best practices and security recommendations
   • Example usage

7. If network tools are unavailable (offline/constrained environment):

   • Continue using local references only
   • State that external version verification could not be performed
   • Add a version-assumption note in the final output

8. Generate pipeline using discovered information:

   • Use correct template include syntax
   • Configure required variables
   • Add security best practices
   • Include comments about versions and choices

Example with GitLab templates:

# Include GitLab's security templates (use Jobs/ prefix for current templates)
include:
  - template: Jobs/SAST.gitlab-ci.yml
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml

# Customize SAST behavior via global variables
# Note: Set variables globally rather than overriding template jobs
# to avoid validation issues with partial job definitions
variables:
  SAST_EXCLUDED_PATHS: "spec, test, tests, tmp, node_modules"
  DS_EXCLUDED_PATHS: "node_modules, vendor"
  SECURE_LOG_LEVEL: "info"

Important: When using include with GitLab templates, the included jobs are fully defined in the template. If you need to customize them, prefer setting variables globally rather than creating partial job overrides (which will fail local validation because the validator cannot resolve the included template). GitLab merges the configuration at runtime, but local validators only see your .gitlab-ci.yml file.

Validation Workflow

CRITICAL: Every generated GitLab CI/CD configuration MUST be validated before presenting to the user.

Validation Process

1. Primary validation path: after generating a complete pipeline, invoke the devops-skills:gitlab-ci-validator skill:

   Skill: devops-skills:gitlab-ci-validator
   

2. Script fallback path (if validator skill cannot be invoked):

   PIPELINE_FILE="<generated-output-path>"
   

   • Set PIPELINE_FILE to the exact generated file path (for example, pipelines/review.yml or .gitlab-ci.yml).
   • Fail fast if that file does not exist:

     if [[ ! -f "$PIPELINE_FILE" ]]; then
       echo "ERROR: CI file not found: $PIPELINE_FILE" >&2
       exit 1
     fi
     

   # From repository root
   bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh "$PIPELINE_FILE"
   

   # From skills/gitlab-ci-generator directory
   bash ../gitlab-ci-validator/scripts/validate_gitlab_ci.sh "$PIPELINE_FILE"
   

   • If the script is not executable:

     chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh
     

   • Optional API lint fallback when GitLab project context is available:

     jq --null-input --arg yaml "$(<"$PIPELINE_FILE")" '.content=$yaml' \
     | curl --header "Content-Type: application/json" \
       --url "https://gitlab.com/api/v4/projects/:id/ci/lint?include_merged_yaml=true" \
       --data @-
     

3. Manual fallback path (only if both primary and script paths are unavailable):

   • Run manual checks for YAML validity, stage/job references, and obvious secret exposure.
   • Mark output as Validation status: Manual fallback (not fully verified).
   • Do not claim production-ready status if Critical/High risk cannot be confidently ruled out.

4. The validator skill/script checks:

   • Validate YAML syntax
   • Check GitLab CI/CD schema compliance
   • Verify job references and dependencies
   • Check for best practices violations
   • Perform security scanning
   • Report any errors, warnings, or issues

5. Analyze validation results and take action based on severity:

   Severity	Action Required
   CRITICAL	MUST fix before presenting. Pipeline is broken or severely insecure.
   HIGH	MUST fix before presenting. Significant security or functionality issues.
   MEDIUM	SHOULD fix before presenting. Apply fixes or explain why not applicable.
   LOW	MAY fix or acknowledge. Inform user of recommendations.
   SUGGESTIONS	Review and apply if beneficial. No fix required.

6. Fix-and-Revalidate Loop (MANDATORY for Critical/High issues):

   While validation has CRITICAL or HIGH issues:
     1. Edit the generated file to fix the issue
     2. Re-run validation
     3. Repeat until no CRITICAL or HIGH issues remain
   

7. Before presenting to user, ensure:

   • Zero CRITICAL issues
   • Zero HIGH issues
   • MEDIUM issues either fixed OR explained why they're acceptable
   • LOW issues and suggestions acknowledged

8. When presenting the validated configuration:

   • State validation status clearly
   • State validation path used (skill, script fallback, or manual fallback)
   • List any remaining MEDIUM/LOW issues with explanations
   • Include template/version freshness notes
   • Provide usage instructions
   • Mention any trade-offs made

Critical/High gate is strict and never optional for production-ready claims.

Validation Pass Criteria

Pipeline is READY to present when:

• ✅ Validation path executed (validator skill or script fallback)
• ✅ Syntax validation: PASSED
• ✅ Security scan: No CRITICAL or HIGH issues
• ✅ Best practices: Reviewed (warnings acceptable with explanation)

Pipeline is NOT READY when:

• ❌ Any syntax errors exist
• ❌ Any CRITICAL security issues exist
• ❌ Any HIGH security issues exist
• ❌ Job references are broken
• ❌ Only manual fallback was used and Critical/High risks cannot be ruled out

When to Skip Validation

Only skip validation when:

• Generating partial code snippets (not complete files)
• Creating examples for documentation purposes
• User explicitly requests to skip validation

Handling MEDIUM Severity Issues (REQUIRED OUTPUT)

When the validator reports MEDIUM severity issues, you MUST either fix them OR explain why they're acceptable. This explanation is REQUIRED in your output.

Required format for MEDIUM issue handling:

## Validation Issues Addressed

### MEDIUM Severity Issues

| Issue | Status | Explanation |
|-------|--------|-------------|
| [Issue code] | Fixed/Acceptable | [Why it was fixed OR why it's acceptable] |

Example MEDIUM issue explanations:

## Validation Issues Addressed

### MEDIUM Severity Issues

| Issue | Status | Explanation |
|-------|--------|-------------|
| `image-variable-no-digest` | Acceptable | Using `python:${PYTHON_VERSION}-alpine` allows flexible version management via CI/CD variables. The PYTHON_VERSION variable is controlled internally and pinned to "3.12". SHA digest pinning would require updating the digest with every image update, adding maintenance burden without significant security benefit for this use case. |
| `pip-without-hashes` | Acceptable | This pipeline installs well-known packages (pytest, flake8) from PyPI. Using `--require-hashes` would require maintaining hash files for all transitive dependencies. For internal CI/CD, the security trade-off is acceptable. For higher security environments, consider using a private PyPI mirror with verified packages. |
| `git-strategy-none` | Acceptable | The `stop-staging` and `rollback-production` jobs use `GIT_STRATEGY: none` because they only run kubectl commands that don't require source code. The scripts are inline in the YAML (not from the repo), so there's no risk of executing untrusted code. |

When to FIX vs ACCEPT:

Reviewing Suggestions (REQUIRED OUTPUT)

When the validator provides suggestions, you MUST briefly acknowledge them and explain whether they should be applied.

Required format:

## Validator Suggestions Review

| Suggestion | Recommendation | Reason |
|------------|----------------|--------|
| [suggestion] | Apply/Skip | [Why] |

Example suggestions review:

## Validator Suggestions Review

| Suggestion | Recommendation | Reason |
|------------|----------------|--------|
| `missing-retry` on test jobs | Skip | Test jobs are deterministic and don't interact with external services. Retry would mask flaky tests rather than fail fast. |
| `parallel-opportunity` for test-unit | Apply if beneficial | Could be added if pytest supports sharding. Add `parallel: 3` with `pytest --shard=${CI_NODE_INDEX}/${CI_NODE_TOTAL}` if test suite is large enough to benefit. |
| `dag-optimization` for stop-staging | Skip | This job is manual and only runs on environment cleanup. DAG optimization wouldn't provide meaningful speedup. |
| `no-dependency-proxy` | Apply for production | Consider using `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` to avoid Docker Hub rate limits. Requires GitLab Premium. |
| `environment-no-url` for rollback | Skip | Rollback jobs don't deploy new versions, so a URL would be misleading. |
| `missing-coverage` for lint job | Skip | Linting doesn't produce coverage data. This is a false positive. |

Template and Version Notes (REQUIRED OUTPUT)

After validation results, include a concise freshness note for templates and documentation assumptions.

Required format:

## Template and Version Notes

- **Template base:** [assets/templates/<file>.yml]
- **Template customization scope:** [what changed from template]
- **Version/doc basis:** [Context7, docs.gitlab.com, or local references only]
- **Freshness note:** [exact date checked, or "external lookup unavailable"]
- **Version-sensitive assumptions:** [if any]

Example:

## Template and Version Notes

- **Template base:** assets/templates/docker-build.yml
- **Template customization scope:** Added unit-test stage and environment-specific deploy rules
- **Version/doc basis:** docs.gitlab.com include-template docs + local references
- **Freshness note:** Verified template syntax on 2026-02-28
- **Version-sensitive assumptions:** Uses `Jobs/SAST.gitlab-ci.yml` template path

Usage Instructions Template (REQUIRED OUTPUT)

After presenting the validated pipeline, you MUST provide usage instructions. This is NOT optional.

Required format:

## Usage Instructions

### Required CI/CD Variables

Configure these variables in **Settings → CI/CD → Variables**:

| Variable | Description | Masked | Protected |
|----------|-------------|--------|-----------|
| [VARIABLE_NAME] | [Description] | Yes/No | Yes/No |

### Setup Steps

1. [First setup step]
2. [Second setup step]
...

### Pipeline Behavior

- **On push to `develop`:** [What happens]
- **On push to `main`:** [What happens]
- **On tag `vX.Y.Z`:** [What happens]

### Customization

[Any customization notes]

Example usage instructions:

## Usage Instructions

### Required CI/CD Variables

Configure these variables in **Settings → CI/CD → Variables**:

| Variable | Description | Masked | Protected |
|----------|-------------|--------|-----------|
| `KUBE_CONTEXT` | Kubernetes cluster context name | No | Yes |
| `KUBE_NAMESPACE_STAGING` | Staging namespace (default: staging) | No | No |
| `KUBE_NAMESPACE_PRODUCTION` | Production namespace (default: production) | No | Yes |

**Note:** `CI_REGISTRY_USER`, `CI_REGISTRY_PASSWORD`, and `CI_REGISTRY` are automatically provided by GitLab.

### Kubernetes Integration Setup

1. **Enable Kubernetes integration** in **Settings → Infrastructure → Kubernetes clusters**
2. **Add your cluster** using the agent-based or certificate-based method
3. **Create namespaces** for staging and production if they don't exist:
   ```bash
   kubectl create namespace staging
   kubectl create namespace production

4. Ensure deployment exists in the target namespaces before running the pipeline

Pipeline Behavior

• On push to develop: Runs tests → builds Docker image → deploys to staging automatically
• On push to main: Runs tests → builds Docker image → manual deployment to production
• On tag vX.Y.Z: Runs tests → builds Docker image → manual deployment to production

Customization

• Update APP_NAME variable to match your Kubernetes deployment name
• Modify environment URLs in deploy-staging and deploy-production jobs
• Add Helm deployment by uncommenting the Helm jobs in the template

## Best Practices to Enforce

Reference `references/best-practices.md` for comprehensive guidelines. Key principles:

### Mandatory Standards

1. **Security First:**
   - Pin Docker images to specific versions (not :latest)
   - Use masked variables for secrets ($CI_REGISTRY_PASSWORD should be masked)
   - Never expose secrets in logs
   - Validate inputs and sanitize variables
   - Use protected variables for sensitive environments

2. **Performance:**
   - Implement caching for dependencies (ALWAYS for npm, pip, maven, etc.)
   - Use `needs` keyword for DAG optimization (ALWAYS when jobs have dependencies)
   - Set artifact expiration to avoid storage bloat (ALWAYS set `expire_in`)
   - Use `parallel` execution *when applicable* (only if test framework supports sharding)
   - Minimize unnecessary artifact passing (use `artifacts: false` in `needs` when not needed)

3. **Reliability:**
   - **Set explicit `timeout` for ALL jobs** (prevents hanging jobs, typically 10-30 minutes)
     - Even when using `default` or `extends` for timeout inheritance, add explicit `timeout` to each job
     - This improves readability and avoids validator warnings about missing timeout
     - Example: A job using `.deploy-template` should still have `timeout: 15 minutes` explicitly set
   - Add retry logic for flaky operations (network calls, external API interactions)
   - Use `allow_failure` appropriately for non-critical jobs (linting, optional scans)
   - Use `resource_group` for deployment jobs (prevents concurrent deployments)
   - Add `interruptible: true` for test jobs (allows cancellation when new commits push)

4. **Naming:**
   - Job names: Descriptive, kebab-case (e.g., "build-application", "test-unit")
   - Stage names: Short, clear (e.g., "build", "test", "deploy")
   - Variable names: UPPER_SNAKE_CASE for environment variables
   - Environment names: lowercase (e.g., "production", "staging")

5. **Configuration Organization:**
   - Use `extends` for reusable configuration (PREFERRED over YAML anchors for GitLab CI)
   - Use `include` for modular pipeline files (organize large pipelines into multiple files)
   - Use `rules` instead of deprecated only/except (ALWAYS)
   - Define `default` settings for common configurations (image, timeout, cache, tags)
   - Use YAML anchors *only when necessary* for complex repeated structures within a single file
     - Note: `extends` is preferred because it provides better visualization in GitLab UI

6. **Error Handling:**
   - Set appropriate timeout values (ALWAYS - prevents hanging jobs)
   - Configure retry behavior for flaky operations (network calls, external APIs)
   - Use `allow_failure: true` for non-blocking jobs (linting, optional scans)
   - Add cleanup steps with `after_script` *when needed* (e.g., stopping test containers, cleanup)
   - Implement notification mechanisms *when required* (e.g., Slack integration for deployment failures)

## Resources

### References (Tiered Loading)

- `references/best-practices.md` (**Tier 1: required for all**) - Comprehensive GitLab CI/CD best practices
  - Security patterns, performance optimization
  - Pipeline design, configuration organization
  - Common patterns and anti-patterns
  - **Use this:** When implementing any GitLab CI/CD resource

- `references/common-patterns.md` (**Tier 1: required for all**) - Frequently used pipeline patterns
  - Basic CI pipeline patterns
  - Docker build and push patterns
  - Deployment patterns (K8s, cloud platforms)
  - Multi-project and parent-child patterns
  - **Use this:** When selecting which pattern to use

- `references/gitlab-ci-reference.md` (**Tier 2: required for Full mode**) - GitLab CI/CD YAML syntax reference
  - Complete keyword reference
  - Job configuration options
  - Rules and conditional execution
  - Variables and environments
  - **Use this:** For syntax and keyword details

- `references/security-guidelines.md` (**Tier 2: required for Full mode**) - Security best practices
  - Secrets management
  - Image security
  - Script security
  - Artifact security
  - **Use this:** For security-sensitive configurations

### Assets (Templates to Customize)

- `assets/templates/basic-pipeline.yml` - Complete basic pipeline template
- `assets/templates/docker-build.yml` - Docker build pipeline template
- `assets/templates/kubernetes-deploy.yml` - Kubernetes deployment template
- `assets/templates/multi-project.yml` - Multi-project orchestration template

**How to use templates:**
1. Copy the relevant template structure
2. Replace all `[PLACEHOLDERS]` with actual values
3. Customize logic based on user requirements
4. Remove unnecessary sections
5. Validate the result

## Typical Workflow Example

**User request:** "Create a CI/CD pipeline for a Node.js app with testing and Docker deployment"

**Process:**
1. ✅ Understand requirements:
   - Node.js application
   - Run tests (unit, lint)
   - Build Docker image
   - Deploy to container registry
   - Trigger on push and merge requests

2. ✅ Reference resources:
   - Check `references/best-practices.md` for pipeline structure
   - Check `references/common-patterns.md` for Node.js + Docker pattern
   - Use `assets/templates/docker-build.yml` as base

3. ✅ Generate pipeline:
   - Define stages (build, test, dockerize, deploy)
   - Create build job with caching
   - Create test jobs (unit, lint) with needs optimization
   - Create Docker build job
   - Add proper artifact management
   - Pin Docker images to versions
   - Include proper secrets handling

4. ✅ Validate:
   - Invoke `devops-skills:gitlab-ci-validator` skill
   - Fix any reported issues
   - Re-validate if needed

5. ✅ Present to user:
   - Show validated pipeline
   - Explain key sections
   - Provide usage instructions
   - Mention successful validation

## Common Pipeline Patterns

### Basic Three-Stage Pipeline
```yaml
stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script: make build

test-job:
  stage: test
  script: make test

deploy-job:
  stage: deploy
  script: make deploy
  when: manual

DAG Pipeline with Needs

stages:
  - build
  - test
  - deploy

build-frontend:
  stage: build
  script: npm run build:frontend

build-backend:
  stage: build
  script: npm run build:backend

test-frontend:
  stage: test
  needs: [build-frontend]
  script: npm test:frontend

test-backend:
  stage: test
  needs: [build-backend]
  script: npm test:backend

deploy:
  stage: deploy
  needs: [test-frontend, test-backend]
  script: make deploy

Conditional Execution with Rules

deploy-staging:
  script: deploy staging
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
      when: always
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

deploy-production:
  script: deploy production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - when: never

Matrix Parallel Jobs

test:
  parallel:
    matrix:
      - NODE_VERSION: ['18', '20', '22']
        OS: ['ubuntu', 'alpine']
  image: node:${NODE_VERSION}-${OS}
  script:
    - npm test

Error Messages and Troubleshooting

If devops-skills:gitlab-ci-validator reports errors:

1. Syntax errors: Fix YAML formatting, indentation, or structure
2. Job reference errors: Ensure referenced jobs exist in needs/dependencies
3. Stage errors: Verify all job stages are defined in stages list
4. Rule errors: Check rules syntax and variable references
5. Security warnings: Address hardcoded secrets and image pinning

If GitLab documentation is not found:

1. Try Context7 first: mcp__context7__resolve-library-id -> mcp__context7__query-docs
2. If needed, run web.search_query scoped to docs.gitlab.com
3. Open specific pages with web.open and extract only required syntax/variables
4. If offline, continue with local references and add version-assumption notes

PRE-DELIVERY CHECKLIST

MANDATORY: Before presenting ANY generated pipeline to the user, verify ALL items:

Mode and References

• Complexity mode selected (Targeted, Lightweight, or Full)
• For Targeted mode: only directly relevant files/references loaded
• For Lightweight/Full modes: read references/best-practices.md before generating
• For Lightweight/Full modes: read references/common-patterns.md before generating
• For Lightweight/Full modes: read appropriate template from assets/templates/ for the pipeline type
• For Full mode: read references/gitlab-ci-reference.md
• For Full mode: read references/security-guidelines.md
• Output explicit confirmation statement for Lightweight/Full modes

Generation Standards Applied

• All Docker images pinned to specific versions (no :latest)
• All jobs have explicit timeout (10-30 minutes typically)
• default block includes timeout if defined
• Hidden templates (.template-name) include timeout
• Caching configured for dependency installation
• needs keyword used for DAG optimization where appropriate
• rules used (not deprecated only/except)
• resource_group configured for deployment jobs
• Artifacts have expire_in set
• Secrets use masked CI/CD variables (not hardcoded)

Validation Completed

• Validation executed via devops-skills:gitlab-ci-validator or script fallback
• Zero CRITICAL issues
• Zero HIGH issues
• MEDIUM issues addressed (fixed OR explained in output using required format)
• LOW issues acknowledged (listed in output)
• Suggestions reviewed (using required format)
• Re-validated after any fixes
• If only manual fallback was available: output marked as not fully verified

Presentation Ready

• Validation status stated clearly
• Validation path stated clearly (skill, script fallback, or manual fallback)
• MEDIUM/LOW issues explained (with table format)
• Suggestions review provided (with table format)
• Template and version notes provided (with required format)
• Usage instructions provided (with required sections)
• Key sections explained

If any checkbox is unchecked, DO NOT present the pipeline. Complete the missing steps first.

Required Output Sections

Use the smallest valid output profile for the selected mode.

Full mode (complete/complex pipeline):

1. Reference Analysis Complete (from Step 3)
2. Generated Pipeline (the .gitlab-ci.yml content)
3. Validation Results Summary (pass/fail status)
4. Validation Issues Addressed (MEDIUM issues table)
5. Validator Suggestions Review (suggestions table)
6. Template and Version Notes (template base + freshness/version assumptions)
7. Usage Instructions (variables, setup, behavior)

Lightweight mode (complete/simple pipeline):

1. Reference Analysis Complete (Lightweight)
2. Generated Pipeline
3. Validation Results Summary
4. Template and Version Notes
5. Usage Instructions

• Add Validation Issues Addressed only when MEDIUM issues exist.
• Add Validator Suggestions Review only when suggestions are present.

Targeted mode (review/Q&A/snippet/focused fix):

• Provide only the directly requested artifact/answer and a concise rationale.
• Include validation/fallback disclosure if validation was not run.
• Do not force full pipeline-generation sections.

Done Criteria

This skill execution is done when:

• Simple requests use Lightweight mode without unnecessary Tier 2 loading.
• Complex requests use Full mode with Tier 2 references and complete confirmation.
• Validation enforces strict Critical/High gates before production-ready claims.
• Output includes template/version freshness notes plus usage instructions.
• Any fallback path is explicit and does not hide verification gaps.

Summary

Always follow this sequence when generating GitLab CI/CD pipelines:

1. Classify Complexity - choose Targeted, Lightweight, or Full mode.
2. Load References - use tiered loading:
   • For Targeted mode, load only directly relevant files.
   • For Lightweight/Full modes, load:
     • references/best-practices.md
     • references/common-patterns.md
     • Plus the appropriate template from assets/templates/
   • For Full mode, also load:
     • references/gitlab-ci-reference.md
     • references/security-guidelines.md
3. Confirm - Output targeted response or Lightweight/Full reference analysis as required by mode.
4. Generate - Use templates and follow standards (security, caching, naming, explicit timeout on ALL jobs).
5. Lookup Docs When Needed - Context7 first, then web.search_query/web.open, with offline fallback notes when constrained.
6. Validate - Use devops-skills:gitlab-ci-validator, script fallback if needed.
7. Fix - Resolve all Critical/High issues, address Medium issues.
8. Verify Checklist - Confirm all pre-delivery checklist items.
9. Present - Deliver output with validation summary, template/version notes, and usage instructions.

Generate GitLab CI/CD pipelines that are:

• ✅ Secure with pinned images and proper secrets handling
• ✅ Following current best practices and conventions
• ✅ Using proper configuration organization (extends, includes)
• ✅ Optimized for performance (caching, needs, DAG)
• ✅ Properly documented with usage instructions
• ✅ Validated with zero Critical/High issues
• ✅ Production-ready and maintainable

GitLab CI/CD Validator

Comprehensive toolkit for validating, linting, testing, and securing .gitlab-ci.yml configurations.

Trigger Phrases

Use this skill when requests include intent like:

• "Validate this .gitlab-ci.yml"
• "Why is this GitLab pipeline failing?"
• "Run a security review for our GitLab CI"
• "Check pipeline best practices"
• "Lint GitLab CI config before merge"

Setup And Prerequisites (Run First)

All commands below assume repository root as current working directory.

# Ensure validator scripts are executable
chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.py

# Required runtime
python3 --version

Use one canonical command path for orchestration:

VALIDATOR="bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh"

Optional local execution tooling (for --test-only):

bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/install_tools.sh

Quick Start Commands

# 1) Full validation (syntax + best practices + security)
$VALIDATOR .gitlab-ci.yml

# 2) Syntax and schema only (required first gate)
$VALIDATOR .gitlab-ci.yml --syntax-only

# 3) Best-practices only (recommended)
$VALIDATOR .gitlab-ci.yml --best-practices

# 4) Security only (required before merge)
$VALIDATOR .gitlab-ci.yml --security-only

# 5) Optional local pipeline structure test (needs gitlab-ci-local + Docker)
$VALIDATOR .gitlab-ci.yml --test-only

# 6) Strict mode (treat best-practice warnings as failure)
$VALIDATOR .gitlab-ci.yml --strict

Deterministic Validation Workflow

Follow these gates in order:

1. Run Quick Start command 2 (--syntax-only).
2. If syntax fails, stop and fix errors before continuing.
3. Run Quick Start command 3 (--best-practices) and apply relevant improvements.
4. Run Quick Start command 4 (--security-only) and fix all critical/high findings before merge.
5. Optionally run Quick Start command 5 (--test-only) for local execution checks.
6. Run Quick Start command 6 (--strict) for final merge gate.

Required gates: syntax + security. Recommended gate: best practices. Optional gate: local execution test.

Rule Severity Rationale And Documentation Links

Severity Model

• critical: Direct credential/secret exposure or high-confidence compromise path. Block merge.
• high: Exploitable unsafe behavior or strong security regression. Fix before merge.
• medium: Security hardening gap with realistic risk. Track and fix soon.
• low/suggestion: Optimization or maintainability improvement.

Rule Classes And Why They Matter

• Syntax rules (yaml-syntax, job-stage-undefined, dependencies-undefined-job): prevent pipeline parse and dependency failures.
• Best-practice rules (cache-missing, artifact-no-expiration, dag-optimization): reduce runtime cost and improve pipeline throughput.
• Security rules (hardcoded-password, curl-pipe-bash, include-remote-unverified): reduce credential leaks and supply-chain risk.

References

• Local syntax reference: devops-skills-plugin/skills/gitlab-ci-validator/docs/gitlab-ci-reference.md
• Local best practices: devops-skills-plugin/skills/gitlab-ci-validator/docs/best-practices.md
• Local common issues: devops-skills-plugin/skills/gitlab-ci-validator/docs/common-issues.md
• GitLab CI YAML reference: https://docs.gitlab.com/ee/ci/yaml/
• GitLab CI/CD components: https://docs.gitlab.com/ee/ci/components/
• GitLab pipeline security guidance: https://docs.gitlab.com/ee/ci/pipelines/settings.html

Fallbacks For Tool Or Environment Constraints

• Missing python3:
  • Behavior: validator cannot run.
  • Fallback: install Python 3 and rerun.
• Missing PyYAML:
  • Behavior: python_wrapper.sh auto-creates .venv and installs pyyaml when possible.
  • Fallback in restricted/offline environments: pre-install pyyaml from an internal mirror, then rerun.
• Missing gitlab-ci-local, node, or docker:
  • Behavior: --test-only reports warning/failure.
  • Fallback: skip local execution testing and continue with syntax/best-practice/security gates.
• No execute permission on scripts:
  • Behavior: shell permission errors.
  • Fallback: rerun the setup chmod command from the Setup section.

Examples

Example 1: New Pipeline Validation

$VALIDATOR examples/basic-pipeline.gitlab-ci.yml --syntax-only
$VALIDATOR examples/basic-pipeline.gitlab-ci.yml --security-only

Example 2: Pre-Merge Hard Gate

$VALIDATOR .gitlab-ci.yml --strict

Example 3: CI Integration

stages:
  - validate

validate_gitlab_ci:
  stage: validate
  script:
    - chmod +x devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.sh devops-skills-plugin/skills/gitlab-ci-validator/scripts/*.py
    - bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_gitlab_ci.sh .gitlab-ci.yml --strict

Individual Validators (Advanced)

# Syntax validator (via wrapper for PyYAML fallback)
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/validate_syntax.py .gitlab-ci.yml

# Best-practices validator
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/check_best_practices.py .gitlab-ci.yml

# Security validator
bash devops-skills-plugin/skills/gitlab-ci-validator/scripts/python_wrapper.sh \
  devops-skills-plugin/skills/gitlab-ci-validator/scripts/check_security.py .gitlab-ci.yml

Done Criteria

• Frontmatter name and description unchanged.
• One canonical orchestrator path is used consistently.
• Setup and chmod prerequisites appear before workflow/use examples.
• Quick-start and workflow are non-duplicative (workflow references quick-start gates).
• Severity rationale and rule-to-doc references are explicit.
• Fallback behavior is documented for missing tools and constrained environments.
• Examples are executable from repository root.

Notes

• This skill validates configuration and static patterns; it does not execute production pipelines.
• Use gitlab-ci-local or GitLab CI Lint for runtime behavior confirmation.

Helm Chart Generator

Overview

Generate production-ready Helm charts with deterministic scaffolding, standard helpers, reusable templates, and validation loops.

Official Documentation:

• Helm Docs - Main documentation
• Chart Best Practices - Official best practices guide
• Template Functions - Built-in functions
• Sprig Functions - Extended function library

When to Use This Skill

Trigger Phrases

Use this skill when prompts include phrases like:

• "create Helm chart"
• "scaffold Helm chart"
• "generate Helm templates"
• "convert manifests to Helm chart"
• "build chart with Deployment/Service/Ingress"

Execution Flow

Follow these stages in order. Do not skip required stages.

Stage 1: Gather Requirements (Required)

Collect:

• Scope: full chart, specific templates, or conversion from manifests
• Workload: deployment, statefulset, or daemonset
• Image reference: repository, optional tag, or digest
• Ports: service port and container target port (separate values)
• Runtime settings: resources, probes, autoscaling, ingress, storage
• Security: service account, security contexts, optional RBAC/network policies

Use request_user_input when critical fields are missing.

If request_user_input is unavailable, ask in normal chat and continue with explicit assumptions.

Do not silently assume critical settings.

Stage 2: Lookup CRD Documentation (Only if CRDs Are In Scope)

1. Try Context7 first:
   • mcp__context7__resolve-library-id
   • mcp__context7__query-docs
2. Fallback chain if Context7 is unavailable or incomplete:
   • Operator official docs (preferred)
   • General web search

Also consult references/crd_patterns.md for example patterns.

Stage 3: Scaffold Chart Structure (Required)

Run:

bash scripts/generate_chart_structure.sh <chart-name> <output-directory> [options]

Options:

• --image <repo> - Supports repo-only, tagged image, registry ports, and digest refs
• --port <number> - Service port (default: 80)
• --target-port <number> - Container target port (default: 8080)
• --type <type> - Workload type: deployment, statefulset, daemonset (default: deployment)
• --with-templates - Generate resource templates (deployment.yaml, service.yaml, etc.)
• --with-ingress - Include ingress template
• --with-hpa - Include HPA template
• --force - Overwrite existing chart without prompting

Image parsing behavior:

• --image nginx:1.27 -> repository nginx, tag 1.27
• --image registry.local:5000/team/app -> repository kept intact
• --image ghcr.io/org/app@sha256:... -> digest mode (no tag concatenation)
• --tag cannot be combined with digest image references

Idempotency and overwrite behavior:

• generate_chart_structure.sh: prompts before overwrite; --force overwrites non-interactively.
• generate_standard_helpers.sh: prompts before replacing templates/_helpers.tpl; --force bypasses prompt.

Expected scaffold shape:

mychart/
  Chart.yaml
  values.yaml
  templates/
    _helpers.tpl
    NOTES.txt
    serviceaccount.yaml
    service.yaml
    configmap.yaml
    secret.yaml
    deployment.yaml|statefulset.yaml|daemonset.yaml
    ingress.yaml (optional)
    hpa.yaml (optional)
  .helmignore

Stage 4: Generate Standard Helpers

Run:

bash scripts/generate_standard_helpers.sh <chart-name> <chart-directory>

Required helpers: name, fullname, chart, labels, selectorLabels, serviceAccountName.

Fallback:

• If script execution is blocked, copy assets/_helpers-template.tpl and replace CHARTNAME with the chart name.

Stage 5: Consult References and Generate Templates (Required)

Consult relevant references once at this stage:

• references/resource_templates.md for the resource patterns being generated
• references/helm_template_functions.md for templating function usage
• references/crd_patterns.md only when CRDs are in scope

Example file-open commands:

sed -n '1,220p' references/resource_templates.md
sed -n '1,220p' references/helm_template_functions.md

Resource coverage from references/resource_templates.md:

• Workloads: Deployment, StatefulSet, DaemonSet, Job, CronJob
• Services: Service, Ingress
• Config: ConfigMap, Secret
• RBAC: ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding
• Network: NetworkPolicy
• Autoscaling: HPA, PodDisruptionBudget

Required template patterns:

metadata:
  name: {{ include "mychart.fullname" . }}
  labels: {{- include "mychart.labels" . | nindent 4 }}

{{- with .Values.nodeSelector }}
nodeSelector: {{- toYaml . | nindent 2 }}
{{- end }}

annotations:
  {{- if and .Values.configMap .Values.configMap.enabled }}
  checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
  {{- end }}

Checksum annotations are required for workloads, but must be conditional and only reference generated templates (configmap.yaml, secret.yaml).

Stage 6: Create values.yaml

Structure guidelines:

• Group related settings logically
• Document every value with # -- comments
• Provide sensible defaults
• Include security contexts, resource limits, probes
• Keep service.port and service.targetPort separate and explicit
• Keep configMap.enabled / secret.enabled aligned with generated templates

See assets/values-schema-template.json for JSON Schema validation.

Stage 7: Validate

Preferred path: run the helm-validator skill.

If skill invocation is unavailable, run local commands directly:

helm lint <chart-dir>
helm template test <chart-dir>

If helm is unavailable, report the block clearly and perform partial checks:

• bash -n scripts/generate_chart_structure.sh
• bash -n scripts/generate_standard_helpers.sh
• Verify generated files and key fields manually

Re-run validation after any fixes.

Template Functions Quick Reference

See references/helm_template_functions.md for complete guide.

Working with CRDs

See references/crd_patterns.md for complete examples.

Key points:

• CRDs you ship -> crds/ directory (not templated, not deleted on uninstall)
• CR instances -> templates/ directory (fully templated)
• Always look up documentation for CRD spec requirements
• Document operator dependencies in Chart.yaml annotations

Converting Manifests to Helm

1. Parameterize: Names -> helpers, values -> values.yaml
2. Apply patterns: Labels, conditionals, toYaml for complex objects
3. Add helpers: Create _helpers.tpl with standard helpers
4. Validate: Run helm-validator (or local lint/template fallback), then test with different values

Error Handling

Example Flows

Full scaffold with templates, ingress, HPA, and explicit port mapping:

bash scripts/generate_chart_structure.sh webapp ./charts \
  --image ghcr.io/acme/webapp:2.3.1 \
  --port 80 \
  --target-port 8080 \
  --type deployment \
  --with-templates \
  --with-ingress \
  --with-hpa

Digest-based image scaffold:

bash scripts/generate_chart_structure.sh api ./charts \
  --image ghcr.io/acme/api@sha256:0123456789abcdef \
  --with-templates

Minimal scaffold without templates:

bash scripts/generate_chart_structure.sh starter ./charts

Scaffold Success Criteria

Mark complete only when all checks pass:

• Chart.yaml, values.yaml, .helmignore, templates/NOTES.txt, and templates/_helpers.tpl exist
• values.yaml contains explicit service.port and service.targetPort
• If --with-templates was used, serviceaccount.yaml, service.yaml, configmap.yaml, secret.yaml, and one workload template exist
• Generated workload template uses conditional checksum annotations for config/secret
• Image rendering logic supports tag and digest modes
• Validation completed (helm-validator skill or local fallback commands) and outcomes reported

Resources

Scripts

References

Assets

Integration with helm-validator

After generating charts, invoke helm-validator and close the loop:

1. Generate chart/templates
2. Run helm-validator (or local fallback commands)
3. Fix identified issues
4. Re-validate until passing

Helm Chart Validator & Analysis Toolkit

Overview

This skill provides a comprehensive validation and analysis workflow for Helm charts, combining Helm-native linting, template rendering, YAML validation, schema validation, CRD documentation lookup, and security best practices checking.

IMPORTANT: This validator is read-only by default. It analyzes charts and proposes improvements. Only modify files when the user explicitly asks to apply fixes.

Trigger Cases

Use this skill when one or more of these top cases apply:

• The user asks to validate, lint, check, test, or troubleshoot a Helm chart
• Helm templates fail to render, lint, or produce valid Kubernetes YAML
• A pre-deployment quality gate is needed (schema, dry-run, security checks)
• CRD resources are present and their spec fields must be verified against docs
• The user wants a severity-based validation report with proposed remediations

Trigger phrase examples:

• "Validate this Helm chart before release"
• "Why does helm template fail?"
• "Check this chart for Kubernetes and security issues"

Out of scope by default:

• New chart scaffolding or broad chart generation (use helm-generator)

Role Boundaries

• This skill validates and reports; it does not silently rewrite user files.
• It can propose concrete patches and apply them only when the user explicitly requests fixes.
• If execution constraints block a stage, it must continue with reachable stages and document the skip reason.

Execution Model

1. Run stages in order (1 through 10).
2. Keep going after stage-level failures to collect complete findings, unless rendering fails and no manifests exist.
3. If Stage 4 produces no manifests, mark Stages 5 to 9 as blocked and continue to Stage 10 reporting.
4. Treat Stage 8 as environment-dependent optional; treat Stage 9 and Stage 10 as mandatory when manifests exist.
5. For every skipped stage, record the exact tool/environment reason in the final summary table.

Quick Execution Modes

Mode A: Local Validation (no cluster required)

bash scripts/setup_tools.sh
bash scripts/validate_chart_structure.sh <chart-directory>
helm lint <chart-directory> --strict
helm template <release-name> <chart-directory> --values <values-file> --debug --output-dir ./rendered
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec yamllint -c assets/.yamllint {} +
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec kubeconform -summary -verbose {} +

Mode B: Full Validation (cluster available)

Run Mode A plus Stage 8 dry-run commands in this document.

Validation & Testing Workflow

Follow this sequential validation workflow. Each stage catches different types of issues:

Stage 1: Tool Check

Before starting validation, verify required tools are installed:

bash scripts/setup_tools.sh

Required tools:

• helm: Helm package manager for Kubernetes (v3+)
• yamllint: YAML syntax and style linting
• kubeconform: Kubernetes schema validation with CRD support
• kubectl: Cluster dry-run testing (optional but recommended)

Fallback policy for unavailable tools or environment constraints:

If tools are missing, provide installation instructions from scripts/setup_tools.sh output and continue with the fallback path above.

Stage 2: Helm Chart Structure Validation

Verify the chart follows the standard Helm directory structure:

bash scripts/validate_chart_structure.sh <chart-directory>

Expected structure:

mychart/
  Chart.yaml          # Chart metadata (required)
  values.yaml         # Default values (required)
  values.schema.json  # JSON Schema for values validation (optional)
  templates/          # Template directory (required)
    _helpers.tpl      # Template helpers (recommended)
    NOTES.txt         # Post-install notes (recommended)
    *.yaml            # Kubernetes manifest templates
  charts/             # Chart dependencies (optional)
  crds/               # Custom Resource Definitions (optional)
  .helmignore         # Files to ignore during packaging (optional)

Common issues caught:

• Missing required files (Chart.yaml, values.yaml, templates/)
• Invalid Chart.yaml syntax or missing required fields
• Malformed values.schema.json
• Incorrect file permissions

Stage 3: Helm Lint

Run Helm's built-in linter to catch chart-specific issues:

helm lint <chart-directory> --strict

Optional flags:

• --values <values-file>: Test with specific values
• --set key=value: Override specific values
• --debug: Show detailed error information

Common issues caught:

• Invalid Chart.yaml metadata
• Template syntax errors
• Missing or undefined values
• Deprecated Kubernetes API versions
• Chart best practice violations

Auto-fix approach:

• For template errors, identify the problematic template file
• Show the user the specific line causing issues
• Propose a patch/diff for the fix
• Apply fixes only if the user explicitly asks
• Re-run helm lint after fixes are applied

Stage 4: Template Rendering

Render templates locally to verify they produce valid YAML:

helm template <release-name> <chart-directory> \
  --values <values-file> \
  --debug \
  --output-dir ./rendered

Options to consider:

• --values values.yaml: Use specific values file
• --set key=value: Override individual values
• --show-only templates/deployment.yaml: Render specific template
• --validate: Validate against Kubernetes OpenAPI schema
• --include-crds: Include CRDs in rendered output
• --is-upgrade: Simulate upgrade scenario
• --kube-version 1.28.0: Target specific Kubernetes version

Common issues caught:

• Template syntax errors (Go template issues)
• Undefined variables or values
• Type mismatches (string vs. integer)
• Missing required values
• Logic errors in conditionals or loops
• Incorrect indentation in nested templates

For template errors:

• Identify the template file and line number
• Check if values are properly defined in values.yaml
• Verify template function usage (quote, required, default, include, etc.)
• Test with different value combinations

Stage 5: YAML Syntax Validation

Validate YAML syntax and formatting of rendered templates:

find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec yamllint -c assets/.yamllint {} +

Common issues caught:

• Indentation errors (tabs vs spaces)
• Trailing whitespace
• Line length violations
• Syntax errors
• Duplicate keys
• Document start/end markers

Auto-fix approach:

• For simple issues (indentation, trailing spaces), propose fixes using the Edit tool
• For template-generated issues, fix the source template, not rendered output
• Always show the user what will be changed before applying fixes

Stage 6: CRD Detection and Documentation Lookup

Before schema validation, detect if the chart contains or renders Custom Resource Definitions:

# Check crds/ directory
if [ -d <chart-directory>/crds ]; then
  find <chart-directory>/crds -type f \( -name "*.yaml" -o -name "*.yml" \) \
    -exec bash scripts/detect_crd_wrapper.sh {} +
fi

# Check rendered templates
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec bash scripts/detect_crd_wrapper.sh {} +

The script outputs JSON with resource information:

[
  {
    "kind": "Certificate",
    "apiVersion": "cert-manager.io/v1",
    "group": "cert-manager.io",
    "version": "v1",
    "isCRD": true,
    "name": "example-cert"
  }
]

For each detected CRD:

1. Try context7 MCP first (preferred):

   Use mcp__context7__resolve-library-id with the CRD project name
   Example: "cert-manager" for cert-manager.io CRDs
            "prometheus-operator" for monitoring.coreos.com CRDs
            "istio" for networking.istio.io CRDs
   
   Then use mcp__context7__query-docs with:
   - libraryId from resolve step
   - query: The CRD kind and relevant features (e.g., "Certificate spec required fields")
   

2. Fallback to web.search_query (web search) if Context7 fails:

   Search query pattern:
   "<kind>" "<group>" kubernetes CRD "<version>" documentation spec
   
   Example:
   "Certificate" "cert-manager.io" kubernetes CRD "v1" documentation spec
   "Prometheus" "monitoring.coreos.com" kubernetes CRD "v1" documentation spec
   

3. Extract key information:

   • Required fields in spec
   • Field types and validation rules
   • Examples from documentation
   • Version-specific changes or deprecations
   • Common configuration patterns

Why this matters: CRDs have custom schemas not available in standard Kubernetes validation tools. Understanding the CRD's spec requirements prevents validation errors and ensures correct resource configuration.

Stage 7: Schema Validation

Validate rendered templates against Kubernetes schemas:

find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) -exec \
  kubeconform \
    -schema-location default \
    -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
    -summary \
    -verbose \
    {} +

Options to consider:

• Add -strict to reject unknown fields (recommended for production)
• Add -ignore-missing-schemas if working with custom/internal CRDs
• Add -kubernetes-version 1.28.0 to validate against specific K8s version
• Add -output json for programmatic processing

Common issues caught:

• Invalid apiVersion or kind
• Missing required fields
• Wrong field types
• Invalid enum values
• Unknown fields (with -strict)

For CRDs: If kubeconform reports "no schema found", this is expected. Use the documentation from Stage 6 to manually validate the spec fields.

Stage 7 success criteria (explicit):

• ✅ Passed: kubeconform exits 0, and no invalid resources are reported.
• ⚠️ Warning: only CRD schema-missing findings remain and Stage 6 documentation/manual verification is completed.
• ❌ Failed: any non-CRD schema violation, parse error, or unresolved required-field/type error.

Stage 8: Cluster Dry-Run (if available)

If kubectl is configured and cluster access is available, perform a server-side dry-run:

# Test installation
helm install <release-name> <chart-directory> \
  --dry-run=server \
  --debug \
  --values <values-file>

# Test upgrade
helm upgrade <release-name> <chart-directory> \
  --dry-run=server \
  --debug \
  --values <values-file>

If the Helm version does not support --dry-run=server, use --dry-run and document that only client-side Helm simulation was executed.

This catches:

• Admission controller rejections
• Policy violations (PSP, OPA, Kyverno, etc.)
• Resource quota violations
• Missing namespaces
• Invalid ConfigMap/Secret references
• Webhook validations
• Existing resource conflicts

If dry-run is not possible:

• Use kubectl with rendered templates: kubectl apply --dry-run=server -f ./rendered/
• Skip if no cluster access
• Document that cluster-specific validation was skipped

For updates to existing releases:

helm diff upgrade <release-name> <chart-directory>

This shows what would change, helping catch unintended modifications. (Requires helm-diff plugin)

Stage 8 success criteria (explicit):

• ✅ Passed: dry-run install and upgrade commands exit 0 with no admission/policy errors.
• ⚠️ Warning: stage skipped because kubectl/cluster context/access is unavailable, or only client-side fallback was possible.
• ❌ Failed: dry-run commands return non-zero due to admission webhooks, policy violations, namespace/quota errors, or reference errors.

Stage 9: Security Best Practices Check (MANDATORY)

IMPORTANT: This stage is MANDATORY. Analyze rendered templates for security best practices compliance.

Check rendered Deployment/Pod templates for:

1. Missing securityContext - Look for pods/containers without security settings:

   # Check if pod-level securityContext exists
   spec:
     securityContext:
       runAsNonRoot: true
       runAsUser: 1000
       fsGroup: 2000
   

2. Missing container securityContext - Each container should have:

   securityContext:
     allowPrivilegeEscalation: false
     readOnlyRootFilesystem: true
     runAsNonRoot: true
     capabilities:
       drop:
         - ALL
   

3. Missing resource limits/requests - Check for:

   resources:
     limits:
       cpu: "100m"
       memory: "128Mi"
     requests:
       cpu: "100m"
       memory: "128Mi"
   

4. Image tag issues - Flag if using :latest or no tag

5. Missing probes - Check for liveness/readiness probes

How to check: Read the rendered deployment YAML files and grep for these patterns:

# Check for securityContext
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep -l "securityContext" {} +

# Check for resources
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep -l "resources:" {} +

# Check for latest tag
find ./rendered -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -exec grep "image:.*:latest" {} +

Stage 10: Final Report (MANDATORY)

IMPORTANT: This stage is MANDATORY even if all validations pass. You MUST complete ALL of the following actions.

Default behavior is read-only. Do not modify files unless the user explicitly asks you to apply fixes.

Step 1: Load Reference Files (MANDATORY when warnings exist)

If ANY warnings, errors, or security issues were found, you MUST read:

Read references/helm_best_practices.md
Read references/k8s_best_practices.md

Use these references to provide context and recommendations for each issue found.

Step 2: Present Validation Summary

Always present a validation summary formatted as a table showing:

• Each validation stage executed (Stages 1-9)
• Status of each stage (✅ Passed, ⚠️ Warning, ❌ Failed)
• Count of issues found per stage

Example:

| Stage | Status | Issues |
|-------|--------|--------|
| 1. Tool Check | ✅ Passed | All tools available |
| 2. Structure | ⚠️ Warning | Missing: .helmignore, NOTES.txt |
| 3. Helm Lint | ✅ Passed | 0 errors |
| 4. Template Render | ✅ Passed | 5 templates rendered |
| 5. YAML Syntax | ✅ Passed | No yamllint errors |
| 6. CRD Detection | ✅ Passed | 1 CRD documented |
| 7. Schema Validation | ✅ Passed | All resources valid |
| 8. Dry-Run | ✅ Passed | No cluster errors |
| 9. Security Check | ⚠️ Warning | Missing securityContext |

Step 3: Categorize All Issues

Group findings by severity:

❌ Errors (must fix):

• Template syntax errors
• Missing required fields
• Schema validation failures
• Dry-run failures

⚠️ Warnings (should fix):

• Deprecated Kubernetes APIs
• Missing securityContext
• Missing resource limits/requests
• Using :latest image tag
• Missing recommended files (_helpers.tpl, .helmignore, NOTES.txt)

ℹ️ Info (recommendations):

• Missing values.schema.json
• Missing README.md
• Optimization opportunities

Step 4: List Proposed Changes (DO NOT APPLY)

For each issue, provide a proposed fix with:

• File path and line number (if applicable)
• Before/after code blocks
• Explanation of why this change is recommended

Example format:

## Proposed Changes

### 1. Add securityContext to Deployment
**File:** templates/deployment.yaml:25
**Severity:** ⚠️ Warning
**Reason:** Running containers as root is a security risk

**Current:**
```yaml
spec:
  containers:
    - name: app
      image: nginx:1.21

Proposed:

spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    fsGroup: 2000
  containers:
    - name: app
      image: nginx:1.21
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop:
            - ALL

2. Add .helmignore file

File: .helmignore (new file) Severity: ⚠️ Warning Reason: Excludes unnecessary files from chart packaging

Proposed: Copy from assets/.helmignore

#### Step 5: Automation Opportunities

List all detected automation opportunities:
- If `_helpers.tpl` is missing → Recommend: `bash scripts/generate_helpers.sh <chart>`
- If `.helmignore` is missing → Recommend: Copy from `assets/.helmignore`
- If `values.schema.json` is missing → Recommend: Copy and customize from `assets/values.schema.json`
- If `NOTES.txt` is missing → Recommend: Create post-install notes template
- If `README.md` is missing → Recommend: Create chart documentation

#### Step 6: Final Summary

Provide a final summary:

Validation Summary

Chart: Status: ⚠️ Warnings Found (or ✅ Ready for Deployment)

Issues Found:

• Errors: X
• Warnings: Y
• Info: Z

Proposed Changes: N changes recommended

Next Steps:

1. Review proposed changes above
2. Apply changes manually or use helm-generator skill
3. Re-run validation to confirm fixes

## Workflow Done Criteria

Validation is complete only when all of the following are true:
- A Stage 1 to Stage 10 status table is present with `✅ Passed`, `⚠️ Warning`, `❌ Failed`, or `⏭️ Skipped` for each stage.
- Every skipped stage includes a concrete tool or environment reason.
- Stage 7 and Stage 8 are evaluated against their explicit success criteria above.
- Severity totals are reported (`Errors`, `Warnings`, `Info`) with proposed remediation actions.
- Role boundary is respected: no file edits unless explicitly requested by the user.

## Helm Templating Automation & Best Practices

This section covers advanced Helm templating techniques, helper functions, and automation strategies.

### Template Helpers (`_helpers.tpl`)

Template helpers are reusable functions defined in `templates/_helpers.tpl`. They promote DRY principles and consistency.

**Standard helper patterns:**

1. **Chart name helper:**
```yaml
{{/*
Expand the name of the chart.
*/}}
{{- define "mychart.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

2. Fullname helper:

{{/*
Create a default fully qualified app name.
*/}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

3. Chart reference helper:

{{/*
Create chart name and version as used by the chart label.
*/}}
{{- define "mychart.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

4. Standard labels helper:

{{/*
Common labels
*/}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
{{ include "mychart.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

5. Selector labels helper:

{{/*
Selector labels
*/}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

6. ServiceAccount name helper:

{{/*
Create the name of the service account to use
*/}}
{{- define "mychart.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "mychart.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}

When to create helpers:

• Values used in multiple templates
• Complex logic that's repeated
• Label sets that should be consistent
• Name generation patterns
• Conditional resource inclusion

Essential Template Functions

Reference and use these Helm template functions for robust charts:

1. required - Enforce required values:

apiVersion: v1
kind: Service
metadata:
  name: {{ required "A valid service name is required!" .Values.service.name }}

2. default - Provide fallback values:

replicas: {{ .Values.replicaCount | default 1 }}

3. quote - Safely quote string values:

env:
  - name: DATABASE_HOST
    value: {{ .Values.database.host | quote }}

4. include - Use helpers with pipeline:

metadata:
  labels:
    {{- include "mychart.labels" . | nindent 4 }}

5. tpl - Render strings as templates:

{{- tpl .Values.customConfig . }}

6. toYaml - Convert objects to YAML:

{{- with .Values.resources }}
resources:
  {{- toYaml . | nindent 2 }}
{{- end }}

7. fromYaml - Parse YAML strings:

{{- $config := .Values.configYaml | fromYaml }}

8. merge - Merge maps:

{{- $merged := merge .Values.override .Values.defaults }}

9. lookup - Query cluster resources (use carefully):

{{- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" }}
{{- if $secret }}
  # Secret exists, use it
{{- else }}
  # Create new secret
{{- end }}

Advanced Template Patterns

1. Conditional resource creation:

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
# ... ingress definition
{{- end }}

2. Range over lists:

{{- range .Values.extraEnvVars }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

3. Range over maps:

{{- range $key, $value := .Values.configMap }}
{{ $key }}: {{ $value | quote }}
{{- end }}

4. With blocks for scoping:

{{- with .Values.nodeSelector }}
nodeSelector:
  {{- toYaml . | nindent 2 }}
{{- end }}

5. Named templates with custom context:

{{- include "mychart.container" (dict "root" . "container" .Values.mainContainer) }}

Values Structure Best Practices

Prefer flat structures when possible:

# Good - Flat structure
serverName: nginx
serverPort: 80

# Acceptable - Nested structure for related settings
server:
  name: nginx
  port: 80
  replicas: 3

Always provide defaults in values.yaml:

replicaCount: 1

image:
  repository: nginx
  pullPolicy: IfNotPresent
  tag: "1.21.0"

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi

Document all values:

# replicaCount is the number of pod replicas for the deployment
replicaCount: 1

# image configures the container image
image:
  # image.repository is the container image registry and name
  repository: nginx
  # image.tag overrides the image tag (default is chart appVersion)
  tag: "1.21.0"

Template Comments and Documentation

Use Helm template comments for documentation:

{{- /*
mychart.fullname generates the fullname for resources.
It supports nameOverride and fullnameOverride values.
Usage: {{ include "mychart.fullname" . }}
*/ -}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

Use YAML comments for user-facing notes:

# WARNING: Changing the storage class will not migrate existing data
storageClass: "standard"

Whitespace Management

Use - to chomp whitespace in template directives:

{{- if .Values.enabled }}
  # Remove leading whitespace
{{- end }}

{{ .Values.name -}}
  # Remove trailing whitespace

Good formatting:

{{- if .Values.enabled }}
  key: value
{{- end }}

Bad formatting:

{{if .Values.enabled}}
key: value
{{end}}

Helper Patterns Reference

When analyzing charts, identify opportunities for helper functions:

1. Identify repetition:

   • Same label sets across resources
   • Repeated name generation logic
   • Common conditional patterns

2. Common helper patterns to recommend:

   • Chart name helper (.name)
   • Fullname helper (.fullname)
   • Chart version label (.chart)
   • Common labels (.labels)
   • Selector labels (.selectorLabels)
   • ServiceAccount name (.serviceAccountName)

3. When to recommend helpers:

   • Missing _helpers.tpl file
   • Repeated code patterns across templates
   • Inconsistent label usage
   • Long resource names that need truncation

Best Practices Reference

For detailed Helm and Kubernetes best practices, load the references:

Read references/helm_best_practices.md
Read references/k8s_best_practices.md

These references include:

• Chart structure and metadata
• Template conventions and patterns
• Values file organization
• Security best practices
• Resource limits and requests
• Common validation issues and fixes

When to load: When validation reveals issues that need context, when implementing new features, or when the user asks about best practices.

Working with Chart Dependencies

When a chart has dependencies (in Chart.yaml or charts/ directory):

1. Update dependencies:

helm dependency update <chart-directory>

2. List dependencies:

helm dependency list <chart-directory>

3. Validate dependencies:

   • Check that dependency versions are available
   • Verify dependency values are properly scoped
   • Test templates with dependency resources

4. Override dependency values:

# values.yaml
postgresql:
  enabled: true
  postgresqlPassword: "secret"
  persistence:
    size: 10Gi

Error Handling Strategies

Tool Not Available

• Run scripts/setup_tools.sh to check availability
• Provide installation instructions
• Skip optional stages but document what was skipped
• Continue with available tools

Template Rendering Errors

• Show the specific template file and line number
• Check if values are defined in values.yaml
• Verify template function syntax
• Test with simpler value combinations
• Use --debug flag for detailed error messages

Cluster Access Issues

• Fall back to client-side validation
• Use rendered templates with kubectl
• Skip cluster validation if no kubectl config
• Document limitations in validation report

CRD Documentation Not Found

• Document that documentation lookup failed
• Attempt validation with kubeconform CRD schemas
• Suggest manual CRD inspection:

  kubectl get crd <crd-name>.group -o yaml
  kubectl explain <kind>
  

Validation Stage Failures

• Continue to next stage even if one fails
• Collect all errors before presenting to user
• Prioritize fixing Helm lint errors first
• Then fix template errors
• Finally fix schema/validation errors

macOS Extended Attributes Issue

Symptom: Helm reports "Chart.yaml file is missing" even though the file exists and is readable.

Cause: On macOS, files created programmatically (via Write tool, scripts, or certain editors) may have extended attributes (e.g., com.apple.provenance, com.apple.quarantine) that interfere with Helm's file detection.

Diagnosis:

# Check for extended attributes
xattr /path/to/chart/Chart.yaml

# If attributes are present, you'll see output like:
# com.apple.provenance
# com.apple.quarantine

Solutions:

1. Remove extended attributes:

   # Remove all extended attributes from a file
   xattr -c /path/to/chart/Chart.yaml
   
   # Remove all extended attributes recursively from chart directory
   xattr -cr /path/to/chart/
   

2. Create files using shell commands instead:

   # Use cat with heredoc instead of direct file writes
   cat > Chart.yaml << 'EOF'
   apiVersion: v2
   name: mychart
   version: 0.1.0
   EOF
   

3. Copy from helm-created chart:

   # Create a fresh chart and copy structure
   helm create temp-chart
   cp -r temp-chart/* /path/to/your/chart/
   rm -rf temp-chart
   

Prevention: When creating new chart files on macOS, prefer using helm create as a base or use shell heredocs (cat > file << 'EOF') rather than direct file creation tools.

Communication Guidelines

When presenting validation results and fixes:

1. Be clear and concise about what was found
2. Explain why issues matter (e.g., "This will cause pod creation to fail")
3. Provide context from Helm best practices when relevant
4. Group related issues (e.g., all missing helper issues together)
5. Use file:line references when available
6. Show confidence level for auto-fixes (high confidence = syntax, low = logic changes)
7. Always provide a summary after proposing fixes (and after applying fixes when explicitly requested) including:
   • What was changed and why
   • File and line references for each fix
   • Total count of issues resolved
   • Final validation status
   • Any remaining warnings or recommendations

Version Awareness

Always consider Kubernetes and Helm version compatibility:

• Check for deprecated Kubernetes APIs
• Ensure Helm chart apiVersion is v2 (for Helm 3+)
• For CRDs, ensure the apiVersion matches what's in the cluster
• Use kubectl api-versions to list available API versions
• Reference version-specific documentation when available
• Set kubeVersion constraint in Chart.yaml if needed

Chart Testing

For comprehensive testing, use Helm test resources:

1. Create test resources:

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "mychart.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
    - name: wget
      image: busybox
      command: ['wget']
      args: ['{{ include "mychart.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

2. Run tests:

helm test <release-name>

Automation Opportunities Reference

During Stage 10 (Final Report), list all detected automation opportunities in the summary.

Do NOT ask user questions or modify files. Simply list recommendations.

Automation opportunities to detect and list:

Security recommendations to include when issues found:

Template improvement recommendations:

Resources

scripts/

setup_tools.sh

• Checks for required validation tools (helm, yamllint, kubeconform, kubectl)
• Provides installation instructions for missing tools
• Verifies versions of installed tools
• Usage: bash scripts/setup_tools.sh

validate_chart_structure.sh

• Validates Helm chart directory structure
• Checks for required files (Chart.yaml, values.yaml, templates/)
• Verifies file formats and syntax
• Usage: bash scripts/validate_chart_structure.sh <chart-directory>

detect_crd_wrapper.sh

• Wrapper script that handles Python dependency management
• Automatically creates temporary venv if PyYAML is not available
• Calls detect_crd.py to parse YAML files
• Usage: bash scripts/detect_crd_wrapper.sh <file.yaml> [file2.yaml ...]

detect_crd.py

• Parses YAML files to identify Custom Resource Definitions
• Extracts kind, apiVersion, group, and version information
• Outputs JSON for programmatic processing
• Requires PyYAML (handled automatically by wrapper script)
• Can be called directly: python3 scripts/detect_crd.py <file.yaml> [file2.yaml ...]

generate_helpers.sh

• Generates standard Helm helpers (_helpers.tpl) for a chart
• Creates fullname, labels, and selector helpers
• Usage: bash scripts/generate_helpers.sh <chart-directory>

references/

helm_best_practices.md

• Comprehensive guide to Helm chart best practices
• Covers template patterns, helper functions, values structure
• Common validation issues and how to fix them
• Security and performance recommendations
• Load when providing context for Helm-specific issues

k8s_best_practices.md

• Comprehensive guide to Kubernetes YAML best practices
• Covers metadata, labels, resource limits, security context
• Common validation issues and how to fix them
• Load when providing context for Kubernetes-specific issues

template_functions.md

• Reference guide for Helm template functions
• Examples of all built-in functions
• Sprig function library reference
• Custom function patterns
• Load when implementing complex templates

assets/

.helmignore

• Standard .helmignore file for excluding files from packaging
• Pre-configured with common patterns

.yamllint

• Pre-configured yamllint rules for Kubernetes YAML
• Follows Kubernetes conventions (2-space indentation, line length, etc.)
• Can be customized per project
• Usage: yamllint -c assets/.yamllint <file.yaml>

values.schema.json

• Example JSON Schema for values validation
• Can be copied and customized for specific charts
• Provides type safety and validation

Jenkinsfile Generator Skill

Generate production-ready Jenkinsfiles following best practices. All generated files are validated using devops-skills:jenkinsfile-validator skill.

Trigger Phrases

• "Generate a CI pipeline for Maven/Gradle/npm"
• "Create a Jenkins deployment pipeline with approvals"
• "Build a Jenkinsfile with parallel test stages"
• "Create a scripted pipeline with dynamic stage logic"
• "Scaffold a Jenkins shared library"
• "Generate a Jenkinsfile for Docker or Kubernetes agents"

When to Use

• Creating new Jenkinsfiles (declarative or scripted)
• CI/CD pipelines, Docker/Kubernetes deployments
• Parallel execution, matrix builds, parameterized pipelines
• DevSecOps pipelines with security scanning
• Shared library scaffolding

Declarative vs Scripted Decision Tree

1. Choose Declarative by default when stage order and behavior are mostly static.
2. Choose Scripted when runtime-generated stages, complex loops, or dynamic control flow are required.
3. Choose Shared Library scaffolding when request is about reusable pipeline functions (vars/, src/, resources/).
4. If unsure, start Declarative and only switch to Scripted if requirements cannot be expressed cleanly.

Template Map

Quick Reference

// Minimal Declarative Pipeline
pipeline {
    agent any
    stages {
        stage('Build') { steps { sh 'make' } }
        stage('Test') { steps { sh 'make test' } }
    }
}

// Error-tolerant stage
stage('Flaky Tests') {
    steps {
        catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE') {
            sh 'run-flaky-tests.sh'
        }
    }
}

// Conditional deployment with approval
stage('Deploy') {
    when { branch 'main'; beforeAgent true }
    input { message 'Deploy to production?' }
    steps { sh './deploy.sh' }
}

Core Capabilities

1. Declarative Pipelines (RECOMMENDED)

Process:

1. Read templates for structure reference:
   • Read assets/templates/declarative/basic.Jenkinsfile to understand the standard structure
   • Templates show the expected sections: pipeline → agent → environment → options → parameters → stages → post
   • For complex requests, adapt the structure rather than copying verbatim
2. Consult reference documentation:
   • Read references/best_practices.md for performance, security, and reliability patterns
   • Read references/common_plugins.md for plugin-specific syntax
3. Generate with required elements:
   • Proper stages with descriptive names
   • Environment block with credentials binding (never hardcode secrets)
   • Options: timeout, buildDiscarder, timestamps, disableConcurrentBuilds
   • Post conditions: always (cleanup), success (artifacts), failure (notifications)
   • Always add failFast true or parallelsAlwaysFailFast() for parallel blocks
   • Always include fingerprint: true when using archiveArtifacts
4. ALWAYS validate using devops-skills:jenkinsfile-validator skill

2. Scripted Pipelines

When: Complex conditional logic, dynamic generation, full Groovy control Process:

1. Read templates for structure reference:
   • Read assets/templates/scripted/basic.Jenkinsfile for node/stage patterns
   • Understand try-catch-finally structure for error handling
2. Implement try-catch-finally for error handling
3. ALWAYS validate using devops-skills:jenkinsfile-validator skill

3. Parallel/Matrix Pipelines

Use parallel {} block or matrix {} with axes {} for multi-dimensional builds.

• Default behavior is fail-fast for generated parallel pipelines (parallelsAlwaysFailFast() or stage-level failFast true).

4. Security Scanning (DevSecOps)

Add SonarQube, OWASP Dependency-Check, Trivy stages with fail thresholds.

5. Shared Library Scaffolding

python3 scripts/generate_shared_library.py --name my-library --package org.example

Declarative Syntax Reference

Agent Types

agent any                                    // Any available agent
agent { label 'linux && docker' }           // Label-based
agent { docker { image 'maven:3.9.11-eclipse-temurin-21' } }
agent { kubernetes { yaml '...' } }         // K8s pod template
agent { kubernetes { yamlFile 'pod.yaml' } } // External YAML

Environment & Credentials

environment {
    VERSION = '1.0.0'
    AWS_KEY = credentials('aws-key-id')     // Creates _USR and _PSW vars
}

Options

options {
    buildDiscarder(logRotator(numToKeepStr: '10'))
    timeout(time: 1, unit: 'HOURS')
    disableConcurrentBuilds()
    timestamps()
    parallelsAlwaysFailFast()
    durabilityHint('PERFORMANCE_OPTIMIZED')  // 2-6x faster for simple pipelines
}

Parameters

parameters {
    string(name: 'VERSION', defaultValue: '1.0.0')
    choice(name: 'ENV', choices: ['dev', 'staging', 'prod'])
    booleanParam(name: 'SKIP_TESTS', defaultValue: false)
}

When Conditions

Add beforeAgent true to skip agent allocation if condition fails.

Error Handling

catchError(buildResult: 'UNSTABLE', stageResult: 'FAILURE') { sh '...' }
warnError('msg') { sh '...' }      // Mark UNSTABLE but continue
unstable(message: 'Coverage low')   // Explicit UNSTABLE
error('Config missing')             // Fail without stack trace

Post Section

post {
    always { junit '**/target/*.xml'; cleanWs() }
    success { archiveArtifacts artifacts: '**/*.jar', fingerprint: true }
    failure { slackSend color: 'danger', message: 'Build failed' }
    fixed { echo 'Build fixed!' }
}

Order: always → changed → fixed → regression → failure → success → unstable → cleanup

NOTE: Always use fingerprint: true with archiveArtifacts for build traceability and artifact tracking.

Parallel & Matrix

IMPORTANT: Always ensure parallel blocks fail fast on first failure using one of these approaches:

Option 1: Global (RECOMMENDED) - Use parallelsAlwaysFailFast() in pipeline options:

options {
    parallelsAlwaysFailFast()  // Applies to ALL parallel blocks in pipeline
}

This is the preferred approach as it covers all parallel blocks automatically.

Option 2: Per-block - Use failFast true on individual parallel stages:

stage('Tests') {
    failFast true  // Only affects this parallel block
    parallel {
        stage('Unit') { steps { sh 'npm test:unit' } }
        stage('E2E') { steps { sh 'npm test:e2e' } }
    }
}

NOTE: When parallelsAlwaysFailFast() is set in options, explicit failFast true on individual parallel blocks is redundant.

stage('Matrix') {
    failFast true
    matrix {
        axes {
            axis { name 'PLATFORM'; values 'linux', 'windows' }
            axis { name 'BROWSER'; values 'chrome', 'firefox' }
        }
        excludes { exclude { axis { name 'PLATFORM'; values 'linux' }; axis { name 'BROWSER'; values 'safari' } } }
        stages { stage('Test') { steps { echo "Testing ${PLATFORM}/${BROWSER}" } } }
    }
}

Input (Manual Approval)

stage('Deploy') {
    input { message 'Deploy?'; ok 'Deploy'; submitter 'admin,ops' }
    steps { sh './deploy.sh' }
}

IMPORTANT: Place input outside steps to avoid holding agents.

Scripted Syntax Reference

node('agent-label') {
    try {
        stage('Build') { sh 'make build' }
        stage('Test') { sh 'make test' }
    } catch (Exception e) {
        currentBuild.result = 'FAILURE'
        throw e
    } finally {
        deleteDir()
    }
}

// Parallel
parallel(
    'Unit': { node { sh 'npm test:unit' } },
    'E2E': { node { sh 'npm test:e2e' } }
)

// Environment
withEnv(['VERSION=1.0.0']) { sh 'echo $VERSION' }
withCredentials([string(credentialsId: 'key', variable: 'KEY')]) { sh 'curl -H "Auth: $KEY" ...' }

@NonCPS for Non-Serializable Operations

@NonCPS
def parseJson(String json) {
    new groovy.json.JsonSlurper().parseText(json)
}

Rules: No pipeline steps (sh, echo) inside @NonCPS. Use for JsonSlurper, iterators, regex Matchers.

Docker & Kubernetes

Docker Agent

agent { docker { image 'maven:3.9.11'; args '-v $HOME/.m2:/root/.m2'; reuseNode true } }

Build & Push

def img = docker.build("myapp:${BUILD_NUMBER}")
docker.withRegistry('https://registry.example.com', 'creds') { img.push(); img.push('latest') }

Kubernetes Pod

agent {
    kubernetes {
        yaml '''
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: maven
    image: maven:3.9.11-eclipse-temurin-21
    command: [sleep, 99d]
'''
    }
}
// Use: container('maven') { sh 'mvn package' }

Shared Libraries

@Library('my-shared-library') _
// or dynamically: library 'my-library@1.0.0'

// vars/log.groovy
def info(msg) { echo "INFO: ${msg}" }

// Usage
log.info 'Starting build'

Validation Workflow

CRITICAL: ALWAYS validate using devops-skills:jenkinsfile-validator skill:

1. Generate Jenkinsfile
2. Invoke devops-skills:jenkinsfile-validator skill
3. Handle validation results by severity:
   • ERRORS: MUST fix before presenting to user - these break the pipeline
   • WARNINGS: SHOULD fix - these indicate potential issues
   • INFO/SUGGESTIONS: Consider applying based on use case:
     • failFast true for parallel blocks → apply by default
     • Build triggers → ask user if they want automated builds
     • Other optimizations → apply if they improve the pipeline
4. Re-validate after fixes
5. Only present validated Jenkinsfiles to user

Validation commands:

# Full validation (syntax + security + best practices)
bash ../jenkinsfile-validator/scripts/validate_jenkinsfile.sh Jenkinsfile

# Syntax only (fastest)
bash ../jenkinsfile-validator/scripts/validate_jenkinsfile.sh --syntax-only Jenkinsfile

Generator Scripts

When to use scripts vs manual generation:

• Use scripts for: Simple, standard pipelines with common patterns (basic CI, straightforward CD)
• Use manual generation for: Complex pipelines with multiple features (parallel tests + security scanning + Docker + K8s deployments), custom logic, or non-standard requirements

Script Arguments: Required vs Optional

• generate_declarative.py
• Required: --output
• Optional: --stages, --agent, --build-tool, --build-cmd, --test-cmd, --deploy-*, --notification-*, --archive-artifacts, --k8s-yaml
• Notes:
• --k8s-yaml accepts either inline YAML content or a path to an existing .yaml/.yml file.
• Stage keys are validated ([a-z0-9_-]) and shell commands are emitted as escaped Groovy literals.
• generate_scripted.py
• Required: --output
• Optional: stage/agent/SCM/notification parameters depending on requested pipeline features.
• generate_shared_library.py
• Required: --name
• Optional: --package, --output
• Shared library deployment helper now includes explicit rollout target (deployment/<name>) and notification helper emits valid HTML email bodies.

# Declarative (simple pipelines)
python3 scripts/generate_declarative.py --output Jenkinsfile --stages build,test,deploy --agent docker

# Scripted (simple pipelines)
python3 scripts/generate_scripted.py --output Jenkinsfile --stages build,test --agent label:linux

# Shared Library (always use script for scaffolding)
python3 scripts/generate_shared_library.py --name my-library --package com.example

Done Criteria

• Pipeline style selection (Declarative vs Scripted) is explicit and justified.
• Generated Jenkinsfiles pass smoke validation with executable validator commands.
• Parallel pipelines are fail-fast by default unless user explicitly requests otherwise.
• Custom stage names and shell commands are safely emitted (no unescaped Groovy literals).
• --k8s-yaml works with both inline YAML and existing file paths.
• Notification-enabled post blocks still archive artifacts when requested.

Plugin Documentation Lookup

Always consult Context7 or WebSearch for:

• Plugins NOT covered in references/common_plugins.md
• Version-specific documentation requests
• Complex plugin configurations or advanced options
• When user explicitly asks for latest documentation

May skip external lookup when:

• Using basic plugin syntax already documented in references/common_plugins.md
• Simple, well-documented plugin steps (e.g., basic sh, checkout scm, junit)

Plugins covered in common_plugins.md: Git, Docker, Kubernetes, Credentials, JUnit, Slack, SonarQube, OWASP Dependency-Check, Email, AWS, Azure, HTTP Request, Microsoft Teams, Nexus, Artifactory, GitHub

Lookup methods (in order of preference):

1. Context7: mcp__context7__resolve-library-id with /jenkinsci/<plugin-name>-plugin
2. WebSearch: Jenkins [plugin-name] plugin documentation 2025
3. Official: plugins.jenkins.io, jenkins.io/doc/pipeline/steps/

References

• references/best_practices.md - Performance, security, reliability patterns
• references/common_plugins.md - Git, Docker, K8s, credentials, notifications
• assets/templates/ - Declarative and scripted templates
• devops-skills:jenkinsfile-validator skill - Syntax and best practices validation