Configuration

Pre-commit Hook Configuration

Basic Configuration

Add py-psscriptanalyzer to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1  # Use the latest version
    hooks:
      - id: py-psscriptanalyzer
      - id: py-psscriptanalyzer-format

Severity Levels

py-psscriptanalyzer uses a hierarchical severity system where each level includes more severe issues:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      - id: py-psscriptanalyzer
        args: ["--severity", "Error"]  # Only show critical errors

Available severity levels (hierarchical):

Information: Shows all issues (Information + Warning + Error) - most comprehensive
Warning: Shows Warning and Error issues (default) - recommended for most projects
Error: Shows only Error issues - most strict, only critical problems
All: Same as Information level

Environment Variables

You can set default severity using environment variables in your CI/CD or local development:

# In GitHub Actions
env:
  SEVERITY_LEVEL: Error

# Or in your pre-commit hook
repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      - id: py-psscriptanalyzer
        # Uses SEVERITY_LEVEL environment variable if set, otherwise defaults to Warning

Command line arguments always override environment variable settings:

export SEVERITY_LEVEL=Error
py-psscriptanalyzer --severity Warning script.ps1  # Uses Warning, not Error

Rule Category Filtering

Filter analysis by rule category:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      - id: py-psscriptanalyzer
        args: ["--security-only"]  # Only show security-related issues

      # Or use other category filters:
      # args: ["--style-only"]
      # args: ["--performance-only"]
      # args: ["--best-practices-only"]
      # args: ["--dsc-only"]
      # args: ["--compatibility-only"]

Include/Exclude Rules

Specify which rules to include or exclude:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      # Include only specific rules
      - id: py-psscriptanalyzer
        name: Security Rules Check
        args: ["--include-rules", "PSAvoidUsingPlainTextForPassword,PSAvoidUsingConvertToSecureStringWithPlainText"]

      # Exclude specific rules
      - id: py-psscriptanalyzer
        name: General Analysis (No Style)
        args: ["--exclude-rules", "PSAvoidSemicolonsAsLineTerminators,PSUseShouldProcessForStateChangingFunctions"]

Output Format Options

Configure different output formats:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      # Generate JSON output
      - id: py-psscriptanalyzer
        args: ["--output-format", "json"]

      # Generate SARIF output for GitHub Code Scanning
      - id: py-psscriptanalyzer
        args: ["--output-format", "sarif", "--output-file", "psscriptanalyzer-results.sarif"]

Recursive File Processing

Use the --recursive flag to automatically find and process all PowerShell files:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      - id: py-psscriptanalyzer
        args: ["--recursive", "--severity", "Error"]
        # This will find all .ps1, .psm1, .psd1 files recursively

CI/CD Integration

GitHub Actions Example

name: PowerShell Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install py-psscriptanalyzer
        run: pip install py-psscriptanalyzer
      - name: Analyze PowerShell files
        env:
          SEVERITY_LEVEL: Error  # Set default severity via environment
        run: py-psscriptanalyzer --recursive

Azure DevOps Example

steps:
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.11'
- script: |
    pip install py-psscriptanalyzer
    export SEVERITY_LEVEL=Warning
    py-psscriptanalyzer --recursive
  displayName: 'Analyze PowerShell Files'

File Patterns

By default, the hooks run on all PowerShell files. You can customize this:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      - id: py-psscriptanalyzer
        files: \\.ps1$  # Only .ps1 files

      - id: py-psscriptanalyzer-format
        files: ^src/.*\\.(ps1|psm1)$  # Only files in src/ directory

Excluding Files

Exclude specific files or directories:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      - id: py-psscriptanalyzer
        exclude: ^(tests/|examples/).*\\.ps1$  # Skip test and example files

Advanced Configuration Examples

Separate Analysis and Formatting

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      # Strict analysis for main code
      - id: py-psscriptanalyzer
        name: PowerShell Analysis (Strict)
        files: ^src/.*\\.ps1$
        args: ["--severity", "Warning"]

      # Lenient analysis for tests
      - id: py-psscriptanalyzer
        name: PowerShell Analysis (Tests)
        files: ^tests/.*\\.ps1$
        args: ["--severity", "Error"]

      # Format all PowerShell files
      - id: py-psscriptanalyzer-format
        name: PowerShell Formatting

Advanced Configuration with New Features

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      # Security-focused analysis
      - id: py-psscriptanalyzer
        name: PowerShell Security Check
        args: ["--security-only", "--severity", "Error"]
        files: ^(src|modules)/.*\.ps1$

      # Style analysis (excluding certain rules)
      - id: py-psscriptanalyzer
        name: PowerShell Style Check
        args: ["--style-only", "--exclude-rules", "PSAvoidSemicolonsAsLineTerminators"]
        files: ^(src|modules)/.*\.ps1$

      # Format all PowerShell files
      - id: py-psscriptanalyzer-format

Integration with Other Hooks

repos:
  # Other language hooks
  - repo: https://github.com/psf/black
    rev: 24.10.0
    hooks:
      - id: black

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff

  # PowerShell hooks
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.1
    hooks:
      - id: py-psscriptanalyzer
      - id: py-psscriptanalyzer-format

PSScriptAnalyzer Configuration

PowerShell Profile Configuration

You can configure PSScriptAnalyzer behavior in your PowerShell profile or via .psscriptanalyzer-settings.psd1 files.

Example Settings File

Create a .psscriptanalyzer-settings.psd1 file in your project root:

@{
    # Severity levels to include
    Severity = @('Error', 'Warning')

    # Rules to exclude
    ExcludeRules = @(
        'PSAvoidUsingWriteHost',  # Allow Write-Host for scripts
        'PSUseShouldProcessForStateChangingFunctions'  # Not applicable for simple scripts
    )

    # Rules to include (if you want to be explicit)
    IncludeRules = @(
        'PSAvoidUsingCmdletAliases',
        'PSAvoidUsingPlainTextForPassword',
        'PSUseDeclaredVarsMoreThanAssignments'
    )

    # Custom rule settings
    Rules = @{
        PSAvoidUsingCmdletAliases = @{
            'allowlist' = @('cd', 'dir', 'type')  # Allow these specific aliases
        }

        PSPlaceOpenBrace = @{
            Enable = $true
            OnSameLine = $true
            NewLineAfter = $true
            IgnoreOneLineBlock = $true
        }

        PSUseConsistentIndentation = @{
            Enable = $true
            IndentationSize = 4
            PipelineIndentation = 'IncreaseIndentationForFirstPipeline'
            Kind = 'space'
        }
    }
}

Environment Variables

Control PSScriptAnalyzer behavior with environment variables:

# Set custom settings file location
export PSSCRIPTANALYZER_SETTINGS="/path/to/custom-settings.psd1"

# Disable automatic PSScriptAnalyzer module installation
export PY_PSSCRIPTANALYZER_NO_INSTALL="1"

# Set custom PowerShell executable
export PY_PSSCRIPTANALYZER_POWERSHELL="/usr/local/bin/pwsh"

CI/CD Configuration

GitHub Actions

name: PowerShell Quality

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install PowerShell
        run: sudo snap install powershell --classic

      - name: Install py-psscriptanalyzer
        run: pip install py-psscriptanalyzer

      - name: Analyze PowerShell files
        run: py-psscriptanalyzer --severity Warning **/*.ps1

      - name: Check formatting
        run: py-psscriptanalyzer --format --dry-run **/*.ps1

Azure DevOps

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.11'

- script: sudo snap install powershell --classic
  displayName: 'Install PowerShell'

- script: pip install py-psscriptanalyzer
  displayName: 'Install py-psscriptanalyzer'

- script: py-psscriptanalyzer --severity Warning **/*.ps1
  displayName: 'Analyze PowerShell files'

Best Practices

Repository Setup

Create settings file: Add .psscriptanalyzer-settings.psd1 to your repository
Configure pre-commit: Use appropriate severity levels for your project
Document exceptions: Comment why specific rules are disabled
Regular updates: Keep py-psscriptanalyzer version up to date

Team Workflow

Standardize settings: Use the same PSScriptAnalyzer configuration across the team
Gradual adoption: Start with errors only, then add warnings
Training: Educate team on PowerShell best practices
Review regularly: Update rules and settings based on team feedback

Performance Optimization

File patterns: Use specific file patterns to avoid analyzing unnecessary files
Exclude patterns: Exclude generated code, vendor code, and test fixtures
Severity levels: Use appropriate severity levels to balance quality and speed
Parallel execution: Pre-commit runs hooks in parallel automatically