Salesforce Multi-Environment Setup

Overview

Configure Salesforce integrations across Developer, Sandbox, and Production orgs with environment-specific credentials, login URLs, and deployment promotion flows.

Prerequisites

• Production Salesforce org (Enterprise+ for Full sandbox)
• Salesforce CLI authenticated to all environments
• Secret management solution (Vault, AWS/GCP Secrets Manager)

Instructions

Step 1: Salesforce Environment Types

Step 2: Sandbox Types

Step 3: Environment Configuration

// src/config/salesforce.ts
interface SalesforceEnvConfig {
  loginUrl: string;
  username: string;
  apiVersion: string;
  isSandbox: boolean;
}

const envConfigs: Record<string, SalesforceEnvConfig> = {
  development: {
    loginUrl: 'https://login.salesforce.com', // Or test.salesforce.com for sandbox
    username: process.env.SF_USERNAME_DEV!,
    apiVersion: '59.0',
    isSandbox: false, // true if using a sandbox for dev
  },
  staging: {
    loginUrl: 'https://test.salesforce.com', // ALL sandboxes use test.salesforce.com
    username: process.env.SF_USERNAME_STAGING!,
    apiVersion: '59.0',
    isSandbox: true,
  },
  production: {
    loginUrl: 'https://login.salesforce.com',
    username: process.env.SF_USERNAME_PROD!,
    apiVersion: '59.0',
    isSandbox: false,
  },
};

export function getSalesforceConfig(): SalesforceEnvConfig {
  const env = process.env.NODE_ENV || 'development';
  const config = envConfigs[env];
  if (!config) throw new Error(`No Salesforce config for environment: ${env}`);
  return config;
}

Step 4: Authenticate to Multiple Orgs

# Authenticate to each environment with aliases
sf org login web --alias sf-dev --instance-url https://login.salesforce.com
sf org login web --alias sf-staging --instance-url https://test.salesforce.com
sf org login web --alias sf-prod --instance-url https://login.salesforce.com

# For CI — use JWT (no browser needed)
sf org login jwt \
  --client-id $SF_CLIENT_ID \
  --jwt-key-file server.key \
  --username ci-user@mycompany.com.staging \
  --alias sf-staging \
  --instance-url https://test.salesforce.com

# List all authenticated orgs
sf org list --all

# Set default org
sf config set target-org sf-dev

Step 5: Secret Management by Environment

# Local development — .env.local (git-ignored)
SF_LOGIN_URL=https://test.salesforce.com
SF_USERNAME=dev-user@mycompany.com.dev
SF_PASSWORD=devpassword
SF_SECURITY_TOKEN=devtoken

# CI/CD (GitHub Actions)
# Use environment-specific secrets:
# Settings > Environments > "staging" > Add secret SF_USERNAME
# Settings > Environments > "production" > Add secret SF_USERNAME (different value)

# Production (Vault / Secrets Manager)
# AWS:
aws secretsmanager get-secret-value --secret-id salesforce/production

# GCP:
gcloud secrets versions access latest --secret=sf-prod-credentials

# HashiCorp Vault:
vault kv get -field=password secret/salesforce/production

Step 6: Deployment Promotion Flow

# 1. Develop in scratch org or developer sandbox
sf project deploy start --target-org sf-dev

# 2. Run Apex tests in dev
sf apex run test --target-org sf-dev --result-format human

# 3. Deploy to staging sandbox
sf project deploy start --target-org sf-staging --test-level RunLocalTests

# 4. Run integration tests against staging
SF_LOGIN_URL=https://test.salesforce.com npm run test:integration

# 5. Deploy to production (requires test coverage)
sf project deploy start --target-org sf-prod --test-level RunLocalTests --wait 30

# Rollback if needed
sf project deploy cancel --target-org sf-prod

Step 7: Environment Guards

// Prevent destructive operations in production
function guardProductionOperation(operation: string): void {
  const config = getSalesforceConfig();

  if (!config.isSandbox && process.env.NODE_ENV === 'production') {
    const blocked = ['deleteAllAccounts', 'truncateContacts', 'resetData'];
    if (blocked.includes(operation)) {
      throw new Error(`Operation '${operation}' blocked in production Salesforce org`);
    }
  }
}

// Prevent using production credentials in dev
function validateEnvironment(): void {
  const config = getSalesforceConfig();
  if (process.env.NODE_ENV === 'development' && !config.isSandbox) {
    console.warn('WARNING: Development mode connected to production org!');
  }
}

Output

• Multi-environment Salesforce configuration
• Sandbox types selected for each environment
• Credentials stored in platform-appropriate secrets manager
• Deployment promotion flow from dev to production
• Environment guards preventing accidental destructive operations

Error Handling

INVALID_LOGIN

test.salesforce.com

.sandbox

user@company.com.sandboxname

Resources

• Sandbox Types
• Sandbox Limitations
• Change Sets
• SFDX CLI Org Commands

Next Steps

For observability setup, see

salesforce-observability