feat: add shellcheck validation to deployment scripts

Add comprehensive shell script linting with shellcheck:

Script Fixes:
- Fix lib/ssh-helpers.sh issues
  - Change ${@:3} to ${*:3} for proper string concatenation
  - Add quotes around variables in comparisons (SC2086)
  - All retry functions now follow best practices

- Fix health-check.sh issues
  - Quote SSH_USER and SSH_HOST variables properly

- Add shellcheck configuration
  - Create .shellcheckrc to disable SC1091 (sourced files)
  - Add shellcheck directives to all scripts

Lint Workflow Integration:
- Add new "shellcheck" job to lint.yml
  - Validates all deployment scripts in parallel
  - Runs on every lint workflow execution
  - Checks compose-workflow repository (owine/compose-workflow)

- Update lint-summary job
  - Include shellcheck results in summary
  - Add shellcheck status to final determination
  - Display shellcheck validation results

- Update Discord notifications
  - Add shellcheck status to validation summary
  - Include dedicated shellcheck failure section
  - Show actionable error messages

Benefits:
✅ Catch common shell scripting errors early
✅ Enforce best practices (quoting, variable usage)
✅ Improve script reliability and maintainability
✅ Validate scripts on every workflow run
✅ Prevent deployment of broken scripts

All deployment scripts now pass shellcheck validation with
best practices enforced across the codebase.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: owine

.github/workflows/lint.yml

@@ -154,6 +154,70 @@ jobs:
       - name: Run actionlint
         uses: raven-actions/actionlint@963d4779ef039e217e5d0e6fd73ce9ab7764e493 # v2.1.0
 
+  shellcheck:
+    name: Shell script validation
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - name: Checkout compose-workflow repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8  # v6.0.1
+        with:
+          repository: owine/compose-workflow
+          ref: main
+
+      - name: Display version information
+        run: |
+          echo "📋 ShellCheck Validation"
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          echo "Repository: compose-workflow (deployment scripts)"
+          echo "Runner: ${{ runner.os }} ${{ runner.arch }}"
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+      - name: Run shellcheck on deployment scripts
+        run: |
+          echo "🐚 Starting ShellCheck validation for deployment scripts..."
+          echo ""
+
+          # Find and validate all shell scripts
+          SCRIPTS=$(find scripts/deployment -name "*.sh" -type f | sort)
+
+          if [ -z "$SCRIPTS" ]; then
+            echo "⚠️  No shell scripts found in scripts/deployment/"
+            exit 0
+          fi
+
+          echo "📁 Scripts to validate:"
+          # shellcheck disable=SC2001
+          echo "$SCRIPTS" | sed 's/^/  • /'
+          echo ""
+
+          # Run shellcheck on all scripts
+          FAILED=0
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+          for script in $SCRIPTS; do
+            echo "🔍 Checking: $script"
+            if shellcheck "$script"; then
+              echo "   ✅ PASSED"
+            else
+              echo "   ❌ FAILED"
+              FAILED=1
+            fi
+            echo ""
+          done
+
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+          if [ $FAILED -eq 0 ]; then
+            echo "🎉 ALL SHELL SCRIPTS PASSED VALIDATION"
+            echo "   All deployment scripts follow best practices"
+          else
+            echo "💥 SHELL SCRIPT VALIDATION FAILED"
+            echo "   Fix the issues shown above"
+            echo "   Run locally: shellcheck scripts/deployment/**/*.sh"
+            exit 1
+          fi
+
   lint:
     strategy:
       matrix:
@@ -358,7 +422,7 @@ jobs:
   lint-summary:
     name: Lint Summary
     runs-on: ubuntu-24.04
-    needs: [scanning, actionlint, lint]
+    needs: [scanning, actionlint, shellcheck, lint]
     if: always()
     timeout-minutes: 5
     steps:
@@ -463,6 +527,26 @@ jobs:
 
           echo ""
 
+          # ShellCheck Shell Script Validation Results
+          echo "🐚 SHELL SCRIPT VALIDATION (SHELLCHECK)"
+          echo "───────────────────────────────────────────────────────────────────────────────────"
+          case "${{ needs.shellcheck.result }}" in
+            "success")
+              echo "✅ PASSED - All deployment scripts follow best practices"
+              SHELLCHECK_OK=true
+              ;;
+            "failure")
+              echo "❌ FAILED - Shell script issues detected"
+              SHELLCHECK_OK=false
+              ;;
+            *)
+              echo "❓ UNKNOWN - Unexpected shellcheck result: ${{ needs.shellcheck.result }}"
+              SHELLCHECK_OK=false
+              ;;
+          esac
+
+          echo ""
+
           # Detailed Lint Results with Error Reproduction
           echo "📋 CODE QUALITY VALIDATION - DETAILED RESULTS"
           echo "───────────────────────────────────────────────────────────────────────────────────"
@@ -580,7 +664,7 @@ jobs:
           echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
           # Final determination
-          if [[ "$SCANNING_OK" == "true" && "$ACTIONLINT_OK" == "true" && "$LINT_OK" == "true" ]]; then
+          if [[ "$SCANNING_OK" == "true" && "$ACTIONLINT_OK" == "true" && "$SHELLCHECK_OK" == "true" && "$LINT_OK" == "true" ]]; then
             echo "🎉 FINAL STATUS: ALL VALIDATION CHECKS PASSED"
             echo "   Repository is ready for deployment"
             exit 0
@@ -591,6 +675,7 @@ jobs:
             echo "   Failed components:"
             [[ "$SCANNING_OK" != "true" ]] && echo "   • GitGuardian security scanning"
             [[ "$ACTIONLINT_OK" != "true" ]] && echo "   • Workflow validation (actionlint)"
+            [[ "$SHELLCHECK_OK" != "true" ]] && echo "   • Shell script validation (shellcheck)"
             [[ "$LINT_OK" != "true" ]] && echo "   • Code quality validation (see detailed errors above)"
             echo ""
             exit 1
@@ -599,7 +684,7 @@ jobs:
   notify:
     name: Discord Notification
     runs-on: ubuntu-24.04
-    needs: [scanning, actionlint, lint, lint-summary]
+    needs: [scanning, actionlint, shellcheck, lint, lint-summary]
     if: always()
     steps:
       - name: Configure 1Password Service Account
@@ -628,6 +713,7 @@ jobs:
 
             **🔒 Security Scan:** ${{ needs.scanning.result == 'success' && '✅ No secrets detected' || needs.scanning.result == 'skipped' && '⏭️ Skipped (PR/manual)' || '❌ Issues found' }}
             **⚙️ Workflow Validation:** ${{ needs.actionlint.result == 'success' && '✅ All workflows valid' || '❌ Issues detected' }}
+            **🐚 Shell Scripts:** ${{ needs.shellcheck.result == 'success' && '✅ Best practices followed' || '❌ Issues detected' }}
             **📋 Code Quality:** ${{ needs.lint.result == 'success' && '✅ All stacks valid' || '❌ Issues detected' }}
 
             **📂 Validated Stacks:** `${{ join(fromJson(inputs.stacks), '`, `') }}`
@@ -641,6 +727,13 @@ jobs:
             • Fix workflow syntax, shellcheck, or expression errors
             • Test locally: `actionlint .github/workflows/*.yml`' || '' }}
 
+            ${{ needs.shellcheck.result == 'failure' && '
+            **🐚 Shell Script Issues:**
+            • Shell script best practices violations detected
+            • Review the **Shell Script Validation** job for details
+            • Fix quoting, variable usage, or syntax issues
+            • Test locally: `shellcheck scripts/deployment/**/*.sh`' || '' }}
+
             ${{ needs.lint.result == 'failure' && '
             **🚨 Action Required:**
             • Review stack validation errors in workflow logs

scripts/deployment/.shellcheckrc

@@ -0,0 +1,4 @@
+# ShellCheck configuration for deployment scripts
+# Disable SC1091 - Not following sourced files
+# This is intentional as library files are in a known location (lib/)
+disable=SC1091

scripts/deployment/cleanup-stack.sh

@@ -7,7 +7,9 @@ set -euo pipefail
 
 # Get script directory and source libraries
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/ssh-helpers.sh
 source "$SCRIPT_DIR/lib/ssh-helpers.sh"
+# shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/common.sh"
 
 # Default values

scripts/deployment/deploy-stacks.sh

@@ -7,6 +7,8 @@ set -euo pipefail
 
 # Get script directory and source libraries
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/ssh-helpers.sh
+# shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/ssh-helpers.sh"
 source "$SCRIPT_DIR/lib/common.sh"
 

scripts/deployment/detect-removed-stacks.sh

@@ -7,6 +7,8 @@ set -euo pipefail
 
 # Get script directory and source libraries
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/ssh-helpers.sh
+# shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/ssh-helpers.sh"
 source "$SCRIPT_DIR/lib/common.sh"
 

scripts/deployment/health-check.sh

@@ -7,6 +7,8 @@ set -euo pipefail
 
 # Get script directory and source libraries
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/ssh-helpers.sh
+# shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/ssh-helpers.sh"
 source "$SCRIPT_DIR/lib/common.sh"
 
@@ -568,7 +570,7 @@ if echo "$HEALTH_RESULT" | grep -q "GITHUB_OUTPUT_START"; then
 else
   log_warning "GITHUB_OUTPUT_START marker not found, attempting to read from temp file..."
   # Try to read from temp file on remote server
-  TEMP_FILE_CONTENT=$(ssh -o "StrictHostKeyChecking no" $SSH_USER@$SSH_HOST 'cat /tmp/github_health_check_outputs.txt 2>/dev/null' || echo "")
+  TEMP_FILE_CONTENT=$(ssh -o "StrictHostKeyChecking no" "$SSH_USER@$SSH_HOST" 'cat /tmp/github_health_check_outputs.txt 2>/dev/null' || echo "")
 
   if [ -n "$TEMP_FILE_CONTENT" ]; then
     log_success "Successfully read outputs from temp file"

scripts/deployment/lib/ssh-helpers.sh

@@ -8,19 +8,19 @@ set -euo pipefail
 retry() {
   local max_attempts=$1
   local delay=$2
-  local command="${@:3}"
+  local command="${*:3}"
   local attempt=1
 
-  while [ $attempt -le $max_attempts ]; do
+  while [ "$attempt" -le "$max_attempts" ]; do
     echo "Attempt $attempt of $max_attempts: $command"
     if eval "$command"; then
       echo "✅ Command succeeded on attempt $attempt"
       return 0
     else
       echo "❌ Command failed on attempt $attempt"
-      if [ $attempt -lt $max_attempts ]; then
+      if [ "$attempt" -lt "$max_attempts" ]; then
         echo "⏳ Waiting ${delay}s before retry..."
-        sleep $delay
+        sleep "$delay"
         delay=$((delay * 2))  # Exponential backoff
       fi
       attempt=$((attempt + 1))
@@ -35,11 +35,11 @@ retry() {
 ssh_retry() {
   local max_attempts=$1
   local delay=$2
-  local ssh_cmd="${@:3}"
+  local ssh_cmd="${*:3}"
   local attempt=1
   local last_exit_code=1
 
-  while [ $attempt -le $max_attempts ]; do
+  while [ "$attempt" -le "$max_attempts" ]; do
     echo "SSH Attempt $attempt of $max_attempts" >&2
     if eval "$ssh_cmd"; then
       echo "✅ SSH command succeeded on attempt $attempt" >&2
@@ -55,9 +55,9 @@ ssh_retry() {
         *) echo "Unknown error code: $last_exit_code" >&2 ;;
       esac
 
-      if [ $attempt -lt $max_attempts ]; then
+      if [ "$attempt" -lt "$max_attempts" ]; then
         echo "⏳ Waiting ${delay}s before SSH retry..." >&2
-        sleep $delay
+        sleep "$delay"
       fi
       attempt=$((attempt + 1))
     fi

scripts/deployment/rollback-stacks.sh

@@ -7,6 +7,8 @@ set -euo pipefail
 
 # Get script directory and source libraries
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/ssh-helpers.sh
+# shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/ssh-helpers.sh"
 source "$SCRIPT_DIR/lib/common.sh"