v3.0.0 - Production Hardening

🔒 Production Hardening

This release transforms the action into a bulletproof primitive suitable for foundational CI/CD use.

Added ➕

• Invariant Validation - Mandatory validation step ensures setup integrity:
  • CLI is installed AND functional (not just present on PATH)
  • Authenticated org is reachable (not just auth succeeded)
  • API version is resolved (not just queried)
  • Fails fast with clear violation messages instead of silent partial failures
• Default Usage Tracking - New outputs enable enforcement hooks in higher-level workflows:
  • used_default_node - Whether default Node.js version (20) was used
  • used_default_cli_version - Whether default CLI version (latest) was used
  • used_default_api_version - Whether API version was auto-detected (always true currently)
  • Allows CI/CD policies to block deployments that rely on implicit defaults
• Dry-Run Mode - New dry_run input skips authentication and mutations while validating detection logic:
  • Useful for testing action configuration without consuming org API calls
  • Skips all auth steps but still installs CLI and resolves environment
• Debug Mode - New debug input placeholder for future verbose output (accepted but not yet implemented)
• Structured Observability - New step publishes audit-friendly summary to GitHub Step Summary:
  • Auth method, org type, API version
  • CLI and Node.js versions
  • Default usage warnings
  • Complete list of installed tools and plugins
  • Always runs (even on failure) for post-mortem analysis
• Forward Compatibility Outputs - Added outputs to support future v4 modularization:
  • cli_binary_path - Absolute path to installed binary (for custom tooling integration)
  • validated_config - JSON summary of effective configuration (for auditing/debugging)

Changed 🔧

• BREAKING (Intentional): Action now fails fast on partial failures
  • Workflows that previously succeeded despite broken CLI or unreachable orgs will now fail
  • This is the correct behavior for a primitive—silent failures are dangerous
  • Example: CLI installed but sf command non-functional → now fails instead of succeeding
• Shell Hardening Enhanced: All bash steps now use strict error handling:
  • Core steps: set -euo pipefail (exit on error, undefined variables, or pipe failures)
  • Optional tooling: set -eu + conditional pipefail based on strict mode
  • Prevents subtle bugs from undefined variables while keeping plugin installs resilient

Fixed 🐞

• Hidden Partial Failure Risk: Action will no longer report success when:
  • CLI installation succeeds but CLI is non-functional
  • Authentication succeeds but org is unreachable
  • Org display succeeds but API version cannot be determined
• Silent Downgrade Risk: Default usage is now explicitly tracked and exposed
  • Prevents workflows from unknowingly relying on implicit defaults
  • Enables explicit versioning enforcement in hardened pipelines

Testing 🧪

• New Test Workflow: test-invariants.yml validates:
  • Invariant validation catches failures correctly
  • Dry-run mode works without authentication
  • Default tracking outputs are accurate
  • All features work across Linux, macOS, Windows

Documentation 📖

• Guaranteed Invariants: New README section documents the action's contract.
• Versioning Policy: Formal semantic versioning governance.
• Caching Strategy: Comprehensive documentation of cache behavior.
• Architecture Documentation: New docs/ARCHITECTURE.md captures design philosophy, current v3 architecture, and future roadmap.

Why This Matters

This action is designed as a primitive, not an application. Primitives must fail loudly and clearly when invariants are violated. Silent partial failures undermine trust in the entire CI/CD pipeline.

Before v3.0.0, it was possible for CLI to install but be non-functional, or auth to succeed but org be unreachable. After v3.0.0, these scenarios fail immediately with actionable error messages.

v2.2.0 - Performance, Reliability & Health Checks 🚀

🚀 New Features - Performance & Caching

• OS-Specific Caching - Cache paths are now partitioned by operating system (Linux/macOS/Windows) to prevent cross-platform corruption and improve hit rates
• Optimized Version Resolution - Uses npm view to resolve "latest" versions 10x faster than a full install, with 10s timeout protection against network hangs
• Smart Hash Detection - Automatically uses sha256sum or shasum -a 256 depending on the runner OS
• CLI Health Verification - Automatic health check after CLI installation validates core plugins are loaded and functional
  • Detects broken installations immediately instead of failing later in workflows
  • Adds ~100ms overhead for significantly improved reliability
  • Runs inline with installation step for fast feedback

Performance 🚀

• Setup time: ~25-55s (cached), ~1.5-3 min (first run) on Ubuntu/macOS
• Cache hit rate: >95% across all platforms
• Health check overhead: ~0.1s (negligible)
• Reliability: Broken installations caught immediately
• Platform note: Windows runners are 10-15x slower; Ubuntu recommended for production CI/CD

🛡️ Reliability & Retries

• Resilient Installation Logic - All network-dependent steps now include 3-attempt retries with exponential backoff:
  • Salesforce CLI (@salesforce/cli)
  • sfdx-git-delta
  • @salesforce/plugin-code-analyzer
  • Custom plugins (each plugin retries individually)
• Improved Cache Fallback - When npm registry is unreachable, cache keys now use monthly time-based rotation (latest-YYYY-MM) instead of static "latest"
  • Prevents indefinite cache staleness during npm outages
  • Automatically rotates monthly to ensure fresh CLI versions
  • Provides clearer error messaging about fallback behavior

Added ➕

• Formal Access Token Support - Added explicit support for auth_method: access-token using the sf org login access-token command (replaces legacy logic)
• Access Token Default - allow_access_token_auth now defaults to true, making this a safe non-breaking change
• New Tests (test-access-token-auth, test-multiple-plugins) to validate complex scenarios
• Enhanced Testing - Added comprehensive CLI health checks to critical and cross-platform test suites
  • Health checks now run on all platforms (Ubuntu, macOS, Windows)
  • Validates CLI version, core plugins, help system, config commands, and org listing
  • Total test coverage increased from ~90% to ~95%
• Workflows: All test workflows now support manual workflow_dispatch triggers for on-demand validation.

Changed 🔧

• Test Architecture Overhaul - Replaced monolithic "Quick Tests" (test.yml) with 4 dedicated workflows (test-critical, test-plugins, test-auth, test-cross-platform)
• Improved Plugin Verification - Test suite now uses jq regex matching to reliably detect namespaced plugins
• Better CLI Validation - Switched verification commands to sf plugins to ensure core plugin availability
• Refactored Retry Tests - Renamed test-network-retry to test-cli-install-retry for clarity
• Enhanced Error Messages - Source directory validation now includes actionable troubleshooting tips
  • Clarifies that force-app is auto-created while custom directories must exist
  • Suggests checking for typos in source_dirs input
  • Reduces support burden with self-service guidance

Fixed 🐞

• Windows Permissions - Fixed file permission warnings for temporary auth files (authurl.txt, access_token.txt) on Windows runners
• Instance URL Handling - Auth logic now correctly strips trailing slashes from instance_url to prevent connection errors
• Custom Plugin Loops - Fixed bash iteration logic to correctly install multiple comma-separated plugins
• Source Flags - Output verification now strictly checks for the --source-dir format
• Dependencies - authurl.txt and access_token.txt added to .gitignore
• Test Consistency - Standardized boolean input format across all test workflows (skip_auth: "true" instead of mixed true/"true")

v2.1.0

Added - Multiple Authentication Methods 🔐

• SFDX Auth URL authentication (auth_method: 'sfdx-url')
  • Simpler alternative to JWT - no certificate required
  • Uses refresh token from SFDX Auth URL
  • New input: sfdx_auth_url
• Access Token authentication (auth_method: 'access-token')
  • Direct access token authentication for advanced use cases
  • New input: access_token
  • Warning: Access tokens are short-lived
• New auth_method input to select authentication type
  • Options: jwt (default), sfdx-url, access-token

Added - Cache Granularity Control ⚡

• New cli_version_for_cache input to control cache key granularity
  • major - Cache busts only on major CLI version changes
  • minor - Cache busts on minor version changes (default)
  • exact - Cache busts on every CLI version change

Added - New Outputs 📊

• api_version - Salesforce API version for the authenticated org
• auth_performed - Whether authentication was performed (true/false)

Changed - Improvements

• Cache key format updated to sf-v3-* for new cache strategy
• Improved sandbox and scratch org detection logic
• Better logging with tree-formatted output
• Environment variables used for sensitive auth data (more secure)

Fixed 🐞

• Windows Support: Resolves file permission issues for authentication on Windows runners.
• Custom plugin installation loop now correctly installs plugins

Release v2.0.1: Fix Marketplace URL

Release v2.0.1 Patch 🐞

📝 Release Notes

This patch release fixes the GitHub Marketplace URL in the documentation to correctly point to setup-salesforce-cli instead of setup-salesforce-action.

Fixed 🐞

• Documentation: Updated README and FILE_SUMMARY links to use the correct Marketplace identifier.

Changes

• Bumped version to 2.0.1

Release v2.0.0: Cross-Platform Support & Enterprise Features

Release v2.0.0 with Cross-Platform Support & Enterprise Features 🚀

📝 Release Notes

This major release brings full cross-platform support (Windows, macOS, Linux), custom plugin support, and significant enterprise enhancements to the Setup Salesforce Action.

🌟 Key Features

🌐 Cross-Platform Support

• Full Windows support with PowerShell and Bash compatibility
• Full macOS support with Homebrew integration
• OS-aware dependency management (jq via apt/brew/choco)
• Secure file handling per platform

🔌 Custom Plugin Support

• Install ANY Salesforce CLI plugin via custom_sf_plugins input
• Smart validation to prevent duplicates
• Safe installation with invalid name protection

📊 Enhanced Outputs & DX

• New source_flags output for seamless multi-directory workflows
• Automatic directory creation (e.g., force-app)
• Improved error messages and validation

⚡ Performance & Improvements

• Platform-specific caching with >95% hit rate
• Resilient networking with exponential backoff retries
• Strict mode for compliance

---

📖 Documentation Updates

• Platform Support Guide
• Testing Strategy
• Quick Start Guide
• Migration Guide

🧪 Testing

• Verified across Ubuntu, Windows, and macOS runners
• Validated with Node 18 and 20
• Comprehensive test suite included

⬆️ Migration

100% Backward Compatible. Simply update your workflow:

- uses: rdbumstead/setup-salesforce-action@v2

See Migration Guide for details.

v1.1.1

Documentation

• Updated author and support links to point to consulting resources
• Refined 'Related Projects' section
• General README formatting improvements

v1.1.0 - Custom Alias Support

What's New in v1.1.0

🎯 Custom Alias Support

You can now specify custom aliases for authenticated orgs, enabling multi-org workflows!

Before (v1.0.0):

- uses: rdbumstead/setup-salesforce-action@v1
          with:
            username: ${{ vars.SFDX_USERNAME }}
            # Always uses alias: "TargetOrg"

After (v1.1.0):

- uses: rdbumstead/setup-salesforce-action@v1
          with:
            username: ${{ vars.DEV_USERNAME }}
            alias: "dev"  # Custom alias!
        
        - uses: rdbumstead/setup-salesforce-action@v1
          with:
            username: ${{ vars.PROD_USERNAME }}
            alias: "prod"  # Different alias!
        
        - run: sf project deploy start --target-org dev
        - run: sf project deploy start --target-org prod

✨ New Features

• Multi-org authentication in single workflow
• Custom org aliases (defaults to TargetOrg for backward compatibility)
• Improved authentication command structure
• Better error handling with proper flag quoting

🐞 Bug Fixes

• Fixed authentication issue with FLAGS variable expansion
• Improved flag quoting for better reliability

📚 Documentation

• Added multi-org workflow example
• Updated configuration reference
• New example file: examples/multi-org.yml

⚙️ Breaking Changes

None! This release is 100% backward compatible.

---

Full Changelog: v1.0.0...v1.1.0

v1.0.0 - Fast Salesforce CLI Setup with JWT Auth

🚀 Initial Release

Fast, flexible, and production-ready Salesforce CLI setup with JWT authentication and optional tooling.

✨ Features

• Lightning Fast Setup - 20-45 seconds with intelligent caching (vs 2-3 min without)
• Secure JWT Authentication - Non-interactive, certificate-based authentication
• Fully Optional Plugins - Install only what you need (delta, scanner, prettier, eslint, lwc-jest)
• Smart Caching - Automatic CLI and plugin caching for 3-5x speedup
• Zero Configuration - Works with minimal inputs, scales to full-stack development
• Dev Hub Support - Set as default Dev Hub with is_dev_hub: 'true'
• Skip Auth Option - CLI-only installation for custom authentication flows

📦 What's Included

Core:

• Salesforce CLI installation
• JWT authentication with automatic key cleanup
• Node.js version control
• Intelligent caching system

Optional Plugins:

• sfdx-git-delta - Delta deployments
• @salesforce/plugin-code-analyzer - Code security scanning

Optional Dev Tools:

• Prettier with Salesforce plugins
• ESLint with LWC plugins
• sfdx-lwc-jest for LWC unit testing

🎯 Quick Start

- name: Setup Salesforce
  uses: rdbumstead/setup-salesforce-action@v1
  with:
    jwt_key: ${{ secrets.SFDX_JWT_KEY }}
    client_id: ${{ secrets.SFDX_CLIENT_ID }}
    username: ${{ vars.SFDX_USERNAME }}

📚 Documentation

See the README for:

• Complete setup guide
• Multiple use case examples
• Performance benchmarks
• Troubleshooting tips

🙏 Feedback Welcome

This is the initial release! Please report bugs, request features, or share feedback via Issues.