salesforce-multi-env-setup

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

Environment	Org Type	Login URL	Purpose	Data
Development	Developer Edition or Scratch Org	login.salesforce.com	Local dev	Sample data
QA	Developer Sandbox	test.salesforce.com	Testing	Subset of prod
Staging	Full Sandbox	test.salesforce.com	Pre-prod validation	Copy of prod
Production	Production Org	login.salesforce.com	Live traffic	Real data

Step 2: Sandbox Types

Sandbox Type	Data	Metadata	Refresh Interval	Use Case
Developer	None	Copy of prod	1 day	Feature development
Developer Pro	None	Copy of prod	1 day	Integration testing
Partial Copy	Sampled	Copy of prod	5 days	QA with realistic data
Full	Full copy	Copy of prod	29 days	Staging, UAT, load testing

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

Issue	Cause	Solution
INVALID_LOGIN in sandbox	Wrong login URL	Use test.salesforce.com for ALL sandboxes
Sandbox username format	Missing .sandbox suffix	Username format: user@company.com.sandboxname
Config merge fails	Wrong NODE_ENV	Verify environment variable
Production guard triggered	Destructive operation	Use sandbox for testing

Resources

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

Next Steps

For observability setup, see salesforce-observability.