Environments

This feature requires sfp-pro with sfp-server

Environments are the central concept in a Flxbl project. An environment links a repository branch to a registered Salesforce org, providing controlled access to credentials for team members and CI/CD pipelines.

Orgs vs Environments

Understanding the distinction between Orgs and Environments is essential:

Concept	Description	Scope
Org	A registered Salesforce org (production, sandbox, scratch org) with stored credentials	Global - shared across all repositories
Environment	A deployment target that links a repository + branch to a registered org	Repository-specific

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Orgs vs Environments                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   REGISTERED ORGS (Global)           ENVIRONMENTS (Per Repository)          │
│   ────────────────────────           ─────────────────────────────          │
│                                                                              │
│   [email protected]    ─────────► Production (myorg/app-1, main)         │
│                           └────────► Production (myorg/app-2, main)         │
│                                                                              │
│   [email protected] ─────────► UAT (myorg/app-1, release/*)           │
│                           └────────► QA (myorg/app-2, develop)              │
│                                                                              │
│   [email protected]        ─────────► (DevHub for scratch org pools)         │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Key differences:

Org Commands (sfp server org)	Environment Commands (sfp server environment)
Register Salesforce credentials	Link orgs to repository branches
Store/update auth details	Control access via locking
JIT sandbox registration	Provide deployment targets
Direct org access via org login	Credential access requires lock or --auth-type

What is an Environment?

An environment represents a deployment target - the combination of:

• Repository: Which codebase (e.g., myorg/salesforce-app)

• Branch: Which code branch (e.g., main, develop)

• Salesforce Org: Which org to install artifacts

• Category: The environment type (dev, test, release)

Environment: "UAT"
├── Repository: myorg/salesforce-app
├── Branch: release/v2.0
├── Salesforce Org: [email protected]  (must be registered first)
├── Category: test
└── Metadata: { "region": "US", "owner": "qa-team" }

Environment Categories

Category	Purpose	Typical Use
dev	Development	Feature development, local testing
test	Testing	UAT, SIT, QA environments
snapshot	Snapshots	Point-in-time environment copies
release	Production	Production and staging releases

Complete Setup: From Org to Environment

Before creating environments, you need to register your Salesforce orgs with sfp-server. Here's the complete flow:

┌─────────────────────────────────────────────────────────────────────────────┐
│                    Environment Setup Flow                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   STEP 1: Register Salesforce Orgs                                           │
│   ────────────────────────────────                                           │
│                                                                              │
│   # Production org (requires local auth first)                               │
│   $ sf org login web --alias production                                      │
│   $ sfp server org register --targetusername production                      │
│                                                                              │
│   # DevHub (if using scratch orgs)                                           │
│   $ sf org login web --alias devhub                                          │
│   $ sfp server org register --targetusername devhub --devhub --default       │
│                                                                              │
│   # Sandboxes (option A: JIT - recommended)                                  │
│   $ sfp server org register-sandbox \                                        │
│       --sandboxname uat \                                                    │
│       --productionusername [email protected]                              │
│                                                                              │
│   # Sandboxes (option B: direct registration)                                │
│   $ sf org login web --alias uat --instance-url https://test.salesforce.com  │
│   $ sfp server org register --targetusername uat                             │
│                                                                              │
│   STEP 2: Create Environments                                                │
│   ───────────────────────────                                                │
│                                                                              │
│   $ sfp server environment create \                                          │
│       --repository myorg/salesforce-app \                                    │
│       --name UAT \                                                           │
│       --category test \                                                      │
│       --branch release/* \                                                   │
│       --targetusername [email protected]                     │
│                                                                              │
│   STEP 3: Access Environments                                                │
│   ───────────────────────────                                                │
│                                                                              │
│   $ sfp server environment get \                                             │
│       --name UAT \                                                           │
│       --repository myorg/salesforce-app \                                    │
│       --auth-type accessToken \                                              │
│       --authenticate                                                         │
│                                                                              │
│   ✅ Ready to use: sfp install --targetorg UAT --artifactdir ./artifacts     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Register Orgs

First, register your Salesforce orgs with sfp-server. See Org Registration for complete details.

Step 2: Create Environments

Link registered orgs to repository branches.

Creating Environments

Basic Creation

sfp server environment create \
  --repository myorg/salesforce-app \
  --name UAT \
  --category test \
  --branch release/v2.0 \
  --description "User Acceptance Testing environment" \
  --targetusername [email protected]

With Metadata and Tags

sfp server environment create \
  --repository myorg/salesforce-app \
  --name Production \
  --category release \
  --branch main \
  --description "Production environment" \
  --targetusername [email protected] \
  --tags "critical,monitored" \
  --metadata '{"region": "US-WEST", "sla": "99.9%"}'

Listing Environments

List All

sfp server environment list --repository myorg/salesforce-app

Output:

┌─────────────┬──────────┬─────────────────┬────────────────────────────┬────────┐
│ Name        │ Category │ Branch          │ Salesforce Org             │ Active │
├─────────────┼──────────┼─────────────────┼────────────────────────────┼────────┤
│ Production  │ release  │ main            │ [email protected]       │ Yes    │
│ Staging     │ release  │ release/*       │ [email protected]  │ Yes    │
│ UAT         │ test     │ release/v2.0    │ [email protected]      │ Yes    │
│ SIT         │ test     │ develop         │ [email protected]      │ Yes    │
│ Dev         │ dev      │ feature/*       │ [email protected]      │ Yes    │
└─────────────┴──────────┴─────────────────┴────────────────────────────┴────────┘

Filter by Category

sfp server environment list --repository myorg/salesforce-app --category test

Retrieving Environments

Basic Retrieval (No Credentials)

Get environment information without credentials:

sfp server environment get --name UAT --repository myorg/salesforce-app

Credential Access Methods

There are two ways to get credentials for an environment:

Method 1: Lock-Based Access (For Deployments)

Recommended for CI/CD and deployments. Locking prevents concurrent deployments from conflicting with each other.

# Step 1: Request a lock
sfp server environment lock \
  --name UAT \
  --repository myorg/salesforce-app \
  --duration 30 \
  --reason "Deploying release v2.0"

# Output: Ticket ID: lock-abc123

# Step 2: Use the ticket to get credentials and authenticate
sfp server environment get \
  --name UAT \
  --repository myorg/salesforce-app \
  --lock-ticket-id lock-abc123 \
  --authenticate

# Step 3: After deployment, release the lock
sfp server environment unlock \
  --name UAT \
  --repository myorg/salesforce-app \
  --ticket-id lock-abc123

Method 2: Direct Access with --auth-type (No Locking)

For testing and read-only operations only. Do not use for deployments - without locking, concurrent operations may conflict.

sfp server environment get \
  --name UAT \
  --repository myorg/salesforce-app \
  --auth-type accessToken \
  --authenticate

This retrieves a short-lived access token (~2 hours) and authenticates locally.

When to Use Which Method

Scenario	Method	Why
CI/CD deployments	Lock-based	Prevents concurrent deployments
Running tests	--auth-type	No locking overhead needed
Quick data queries	--auth-type	Read-only, no conflict risk
Long-running operations	Lock with --wait	Ensures exclusive access
Parallel pipeline jobs	Lock-based	Queue management

Auth Type Selection

Auth Type	Lifetime	Use Case
accessToken	~2 hours	Short operations, better security
sfdxAuthUrl	Until revoked	Scratch org pools, extended sessions

Environment Properties

Core Properties

Property	Description
name	Unique name within repository
category	dev, test, snapshot, release
branch	Git branch pattern
description	Human-readable description
salesforceUsername	Linked Salesforce org
isActive	Whether environment is active
isDefault	Default for its category

Extended Properties

Property	Description
tags	Searchable tags
metadata	Custom JSON metadata
orchestrationOrder	Deployment sequence
devHubUsername	Parent org (for sandboxes)

Lock Status

When an environment is locked:

{
  "name": "UAT",
  "isLocked": true,
  "lockStatus": {
    "isLocked": true,
    "currentLock": {
      "lockedBy": "ci-pipeline",
      "lockReason": "Deployment in progress",
      "expiresAt": "2024-01-15T14:30:00Z",
      "expiresInSeconds": 1800
    },
    "queuedLocks": [
      {
        "position": 1,
        "requestedBy": "[email protected]",
        "ticketId": "lock-abc123"
      }
    ]
  }
}

Updating Environments

sfp server environment update \
  --name UAT \
  --repository myorg/salesforce-app \
  --description "Updated UAT for Q2 release" \
  --tags "critical,q2-release"

Deleting Environments

sfp server environment delete \
  --name old-dev \
  --repository myorg/salesforce-app

Credential Access Control

Role-Based Access

Role	Can View	Can Get Credentials	Can Modify
Member	Yes	No	No
Owner	Yes	Yes	Yes
Application	Yes	Yes	Limited

Audit Trail

All credential access is logged:

# View access audit (owners only)
sfp server environment audit --name UAT --repository myorg/salesforce-app

CI/CD Integration

GitHub Actions

jobs:
  deploy-to-uat:
    runs-on: ubuntu-latest
    env:
      SFP_SERVER_URL: ${{ secrets.SFP_SERVER_URL }}
      SFP_SERVER_TOKEN: ${{ secrets.SFP_SERVER_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - name: Authenticate to UAT
        run: |
          sfp server environment get \
            --name UAT \
            --repository ${{ github.repository }} \
            --auth-type accessToken \
            --authenticate

      - name: Deploy
        run: |
          sfp install --targetorg UAT --artifactdir ./artifacts

Matrix Deployment

jobs:
  deploy:
    strategy:
      matrix:
        environment: [SIT, UAT, Staging]
    runs-on: ubuntu-latest
    steps:
      - name: Authenticate
        run: |
          sfp server environment get \
            --name ${{ matrix.environment }} \
            --repository ${{ github.repository }} \
            --auth-type accessToken \
            --authenticate

      - name: Deploy to ${{ matrix.environment }}
        run: |
          sfp install --targetorg ${{ matrix.environment }} --artifactdir ./artifacts

Environment Patterns

Standard Pipeline

Repository: myorg/salesforce-app

Environments:
├── Dev (dev) ────────> feature branches
│
├── SIT (test) ────────> main
│
├── UAT (test) ────────> main
│
├── Staging (release) ─> main 
│
└── Production (release) ─> main branch

Multi-Region

Environments:
├── Production-US (release, tags: ["us", "primary"])
├── Production-EU (release, tags: ["eu", "gdpr"])
└── Production-APAC (release, tags: ["apac"])

Feature Environments

Environments:
├── Feature-Auth (dev, branch: feature/auth-*)
├── Feature-Payments (dev, branch: feature/payments-*)
└── Feature-Reports (dev, branch: feature/reports-*)

Related Topics

• Server Authentication - Authenticate with sfp-server

• Org Registration - Register orgs for environments

• Environment Locking - Concurrent access control

• Accessing Environments - Practical examples

• JIT Sandbox Authentication - On-demand sandbox credentials