Super-Linter Best Practices

Core Principles

MUST follow these principles:

Principle	Rule
Configuration files	MUST be perfect - no errors
Mirror CI locally	ALWAYS use pre-commit hooks
Exclude auto-generated files	NEVER lint files you don't control
Resolve tool conflicts	MUST fix ESLint configuration conflicts

super-linter.env Configuration

File Format Requirements

MUST follow these rules strictly:

# ❌ WRONG - Comments not allowed
VALIDATE_JSON=false  # Disable JSON linting

# ❌ WRONG - Keys not alphabetically sorted
VALIDATE_YAML=false
VALIDATE_JSON=false

# ❌ WRONG - Blank lines not allowed
VALIDATE_JSON=false

VALIDATE_YAML=false

# ✅ CORRECT - No comments, sorted, no blanks
FILTER_REGEX_EXCLUDE=.*(CHANGELOG\.md|package-lock\.json|node_modules|dist|build).*
VALIDATE_JSON=false
VALIDATE_YAML=false

Alphabetical Ordering Rules

MUST use strict ASCII alphabetical order:

Example	Correct Order
JSCPD vs JSON_PRETTIER	VALIDATE_JSCPD before VALIDATE_JSON_PRETTIER
TERRASCAN vs TFLINT	VALIDATE_TERRAFORM_TERRASCAN before VALIDATE_TERRAFORM_TFLINT

MUST verify with sort command:

sort .github/linters/super-linter.env -o .github/linters/super-linter.env

Common Configuration Template

FILTER_REGEX_EXCLUDE=.*(node_modules|dist|build|vendor|\.next|\.nuxt|_site|coverage|test-results|\.min\.js|package-lock\.json|CHANGELOG\.md).*
VALIDATE_ALL_CODEBASE=false
VALIDATE_BIOME_FORMAT=false
VALIDATE_BIOME_LINT=false
VALIDATE_CHECKOV=false
VALIDATE_CSS=false
VALIDATE_CSS_PRETTIER=false
VALIDATE_GITHUB_ACTIONS_ZIZMOR=false
VALIDATE_JAVASCRIPT_PRETTIER=false
VALIDATE_JSCPD=false
VALIDATE_JSON_PRETTIER=false
VALIDATE_MARKDOWN=false
VALIDATE_MARKDOWN_PRETTIER=false
VALIDATE_NATURAL_LANGUAGE=false
VALIDATE_SHELL_SHFMT=false
VALIDATE_TERRAFORM_FMT=false
VALIDATE_TERRAFORM_TERRASCAN=false
VALIDATE_TERRAFORM_TFLINT=false
VALIDATE_TERRAGRUNT=false
VALIDATE_TRIVY=false
VALIDATE_YAML_PRETTIER=false

Common Error Patterns

Pattern 1: ENV File Ordering

Error: "The VALIDATE_X key should go before the VALIDATE_Y key"

Cause: Keys not in alphabetical order

Fix:

sort .github/linters/super-linter.env -o .github/linters/super-linter.env

Pattern 2: ESLint Quote Conflicts

Error: ESLint reports quote style violations

Cause: Code uses double quotes but ESLint requires single quotes

Fix: Run eslint --fix:

npx eslint . --fix

Pattern 3: Unused Variables in Catch Blocks

Error: "'error' is defined but never used"

Fix: Use anonymous catch blocks:

// ❌ Before
try {
  await operation();
} catch (error) {
  return null;
}

// ✅ After
try {
  await operation();
} catch {
  return null;
}

Pattern 4: TOCTOU Race Conditions (CodeQL)

Error: "The file may have changed since it was checked"

Cause: Checking file existence separately from reading it

Fix: Read the file directly in try-catch:

// ❌ Before - race condition
const exists = await fs
  .stat(path)
  .then(() => true)
  .catch(() => false);
const data = await fs.readFile(path, 'utf-8');

// ✅ After - atomic operation
const data = await fs.readFile(path, 'utf-8'); // Will throw if missing

Pattern 5: Auto-Generated Files Failing

Error: CHANGELOG.md, package-lock.json fail linting

Fix: Multiple exclusion strategies:

# In super-linter.env
FILTER_REGEX_EXCLUDE=.*(CHANGELOG\.md|package-lock\.json|node_modules).*

# In .gitattributes
CHANGELOG.md linguist-generated=true
package-lock.json linguist-generated=true

# In .eslintignore
CHANGELOG.md
package-lock.json

Pre-Commit Hook Integration

ENV File Alphabetical Check

- id: env-file-alphabetical
  name: Check .env files are alphabetically sorted
  entry: scripts/pre-commit-check-env-sort.sh
  language: script
  pass_filenames: false
  files: \.env$

Complete Pre-Commit Script

#!/usr/bin/env bash
set -e

env_files=$(find . -name "*.env" \
  -not -path "*/node_modules/*" \
  -not -path "*/.git/*")

exit_code=0

for file in $env_files; do
  keys=$(grep -E "^[A-Z_]+=" "$file" | cut -d= -f1)
  sorted_keys=$(echo "$keys" | sort)

  if [ "$keys" != "$sorted_keys" ]; then
    echo "❌ $file: Keys are not alphabetically sorted"
    exit_code=1
  fi
done

exit $exit_code

Debugging Super-Linter Failures

Run Super-Linter Locally

MUST test locally before pushing:

docker run \
  -e RUN_LOCAL=true \
  -e USE_FIND_ALGORITHM=true \
  -e VALIDATE_ALL_CODEBASE=false \
  -v $(pwd):/tmp/lint \
  ghcr.io/super-linter/super-linter:slim-v8

Check Specific Linter

docker run \
  -e RUN_LOCAL=true \
  -e VALIDATE_ENV=true \
  -e VALIDATE_ALL_CODEBASE=true \
  -v $(pwd):/tmp/lint \
  ghcr.io/super-linter/super-linter:slim-v8

Fetch GitHub Actions Logs

gh run view --log | grep -A 20 "ERROR"

Migration Strategy

Phase 1: Discovery (Day 1)

1. Add Super-Linter workflow with all linters enabled
2. Set VALIDATE_ALL_CODEBASE=false (only check changed files)
3. Run on a test PR to discover failures
4. Document all failure types

Phase 2: Quick Wins (Day 2-3)

1. Exclude auto-generated files
2. Fix formatting issues (eslint --fix)
3. Remove unused variables
4. Disable problematic linters temporarily

Phase 3: Address Issues (Week 1)

1. Fix remaining code quality issues
2. Configure tool compatibility
3. Add pre-commit hooks
4. Document linter disable reasons

Phase 4: Full Coverage (Week 2+)

1. Fix all existing violations
2. Re-enable previously disabled linters
3. Set VALIDATE_ALL_CODEBASE=true
4. Enforce in CI/CD

Performance Optimization

Optimization	Implementation
Slim image	MUST use super-linter/super-linter/slim
Incremental	SHOULD use VALIDATE_ALL_CODEBASE=false
Caching	SHOULD cache dependencies

Optum-Specific Integration

Required Workflow via Organization Ruleset

At Optum, Super-Linter runs automatically via:

Setting	Value
Reusable workflow	ohemr-action-library/.github/workflows/reuseable-lint.yml
Effect	All PRs MUST pass before merge
Version	v8.2.0 slim (pinned)
Optum fork	optum-tech-compute/super-linter

Pre-commit Hook Strategy

MUST use pre-commit framework (Python-based):

pip install pre-commit
pre-commit install

NEVER use:

• Husky (npm-based hooks) - avoided to prevent overlap
• Manual .git/hooks/ scripts

Security Scanning

Scanner	Status	Notes
Gitleaks	ALWAYS enabled	Secret scanning
CodeQL	Separate workflow	Handled by Code-Review-Agent
ZIZMOR	Disabled	False positives on reusable workflows

Troubleshooting Checklist

• VERIFY super-linter.env format (no comments, sorted keys)
• CHECK alphabetical ordering of VALIDATE_* keys
• REMOVE unused variables in catch blocks
• RUN eslint --fix for code style issues
• EXCLUDE auto-generated files
• TEST locally with Docker Super-Linter
• REVIEW GitHub Actions logs for specific errors
• CHECK for tool conflicts (linter disagreements)
• UPDATE pre-commit hooks to mirror CI

Key Takeaways

Principle	Rule
super-linter.env format	MUST be strict: no comments, alphabetically sorted
Tool conflicts	ALWAYS resolve linter disagreements
Generated files	NEVER lint what you don't write
Local testing	MUST test with Docker before CI
Security	NEVER disable security checks
Documentation	MUST explain why linters are disabled
Adoption	PREFER incremental over big-bang
CI mirroring	MUST use pre-commit hooks

When in doubt, ALWAYS prioritize security and correctness over convenience.