Accessing Environments
This guide walks through common scenarios for accessing environments with sfp-server, from local development to production deployments.
Complete Flow: From Login to Deployment
Here's the complete end-to-end flow for a developer to access an environment and deploy:
┌─────────────────────────────────────────────────────────────────────────────┐
│ End-to-End Authentication Flow │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: Authenticate to sfp-server (one-time until token expires) │
│ ───────────────────────────────────────────────────────────────── │
│ │
│ $ sfp server auth login --email [email protected] --provider github │
│ │
│ ┌────────────┐ │
│ │ Browser │ → GitHub OAuth → Authorize → Callback to CLI │
│ └────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ Keychain │ Token stored securely (valid ~24h) │
│ └────────────┘ │
│ │
│ STEP 2: Get environment and authenticate locally │
│ ──────────────────────────────────────────────── │
│ │
│ $ sfp server environment get \ │
│ --name UAT \ │
│ --repository myorg/salesforce-app \ │
│ --auth-type accessToken \ │
│ --authenticate │
│ │
│ ┌────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Keychain │────>│ sfp-server │────>│ Salesforce │ │
│ │ (get token)│ │ API │ │ Auth │ │
│ └────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ │ │ Decrypt & │ │
│ │ │ return creds │ │
│ │<──────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────┘ │
│ Create local SF auth (alias: "UAT") │
│ │
│ STEP 3: Use sfp commands with the authenticated org │
│ ─────────────────────────────────────────────────── │
│ │
│ $ sfp install --targetorg UAT --artifactdir ./artifacts │
│ $ sfp release --targetorg UAT --releasedefinition ./release.yaml │
│ │
│ ✅ The org "UAT" is now available for all sfp and sf commands │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Quick Start Commands
# 1. Login to sfp-server (interactive, opens browser)
sfp server auth login --email [email protected] --provider github
# 2. Verify you're authenticated
sfp server auth display
# 3. List available environments
sfp server environment list --repository myorg/salesforce-app
# 4. Access an environment (this authenticates you to the Salesforce org)
sfp server environment get \
--name UAT \
--repository myorg/salesforce-app \
--auth-type accessToken \
--authenticate
# 5. Use the authenticated org
sfp install --targetorg UAT --artifactdir ./artifactsScenario 1: Local Development
As a developer, you need to access a development environment for daily work.
One-time Setup
# 1. Authenticate with sfp-server (one-time or when token expires)
sfp server auth login --provider github
# Verify authentication
sfp server auth displayInstalling an artifact
# Get your dev environment
sfp server environment get \
--name dev \
--repository myorg/salesforce-app \
--auth-type accessToken \
--authenticate
# Start developing - org is now authenticated locally as "Dev"
sfp install -o dev -v devhub -p core
Switching Environments
# Switch to UAT for testing
sfp server environment get \
--name UAT \
--repository myorg/salesforce-app \
--auth-type accessToken \
--authenticate
# Deploy to UAT
sfp install --targetorg UAT --artifactdir ./artifactsScenario 2: CI/CD Pipeline Deployment
Setting up a GitHub Actions workflow that deploys to multiple environments.
Repository Secrets Setup
Configure these secrets in your repository:
SFP_SERVER_URL- Your sfp-server URLSFP_SERVER_TOKEN- Application token for CI/CD
Basic Deployment Workflow
name: Deploy to UAT
on:
push:
branches: [develop]
jobs:
deploy:
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: Install sfp
run: npm install -g @flxbl-io/sfp
- name: Get UAT Environment
run: |
sfp server environment get \
--name UAT \
--repository ${{ github.repository }} \
--auth-type accessToken \
--authenticate
- name: Deploy Artifacts
run: |
sfp install \
--targetorg UAT \
--artifactdir ./artifactsProduction Deployment with Locking
name: Production Release
on:
release:
types: [published]
jobs:
deploy-production:
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: Install sfp
run: npm install -g @flxbl-io/sfp
- name: Request Lock
id: lock
run: |
RESULT=$(sfp server environment lock \
--name Production \
--repository ${{ github.repository }} \
--reason "Release ${{ github.ref_name }}" \
--lease-duration 60 \
--json)
echo "ticket_id=$(echo $RESULT | jq -r '.ticketId')" >> $GITHUB_OUTPUT
- name: Acquire Lock and Authenticate
run: |
sfp server environment get \
--name Production \
--repository ${{ github.repository }} \
--lock-ticket-id ${{ steps.lock.outputs.ticket_id }} \
--authenticate
- name: Deploy to Production
run: |
sfp release \
--targetorg Production \
--releasedefinition ./release-definition.yaml
- name: Release Lock
if: always()
run: |
sfp server environment unlock \
--name Production \
--repository ${{ github.repository }} \
--lock-ticket-id ${{ steps.lock.outputs.ticket_id }}Scenario 3: Multi-Environment Pipeline
A complete pipeline that progresses through SIT → UAT → Staging → Production.
name: Progressive Deployment
on:
workflow_dispatch:
inputs:
environment:
description: 'Target environment'
required: true
type: choice
options:
- SIT
- UAT
- Staging
- Production
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ github.event.inputs.environment }}
env:
SFP_SERVER_URL: ${{ secrets.SFP_SERVER_URL }}
SFP_SERVER_TOKEN: ${{ secrets.SFP_SERVER_TOKEN }}
steps:
- uses: actions/checkout@v4
- name: Install sfp
run: npm install -g @flxbl-io/sfp
- name: Request Lock
id: lock
run: |
RESULT=$(sfp server environment lock \
--name ${{ github.event.inputs.environment }} \
--repository ${{ github.repository }} \
--reason "Deployment triggered by ${{ github.actor }}" \
--json)
echo "ticket_id=$(echo $RESULT | jq -r '.ticketId')" >> $GITHUB_OUTPUT
- name: Authenticate
run: |
sfp server environment get \
--name ${{ github.event.inputs.environment }} \
--repository ${{ github.repository }} \
--lock-ticket-id ${{ steps.lock.outputs.ticket_id }} \
--authenticate
- name: Deploy
run: |
sfp install \
--targetorg ${{ github.event.inputs.environment }} \
--artifactdir ./artifacts
- name: Run Tests
run: |
sfp test run \
--targetorg ${{ github.event.inputs.environment }}
- name: Release Lock
if: always()
run: |
sfp server environment unlock \
--name ${{ github.event.inputs.environment }} \
--repository ${{ github.repository }} \
--lock-ticket-id ${{ steps.lock.outputs.ticket_id }}Scenario 4: Team Access Setup
Setting up environments for a team with different access levels.
Initial Setup (Admin/Owner)
# 1. Authenticate as admin
sfp server auth login --admin --email [email protected]
# 2. Register the production org
sf org login web --alias production
sfp server org register --targetorg production
# 3. Register DevHub
sf org login web --alias devhub
sfp server org register --targetorg devhub --is-devhub --is-default
# 4. Register sandboxes with JIT
sfp server org register-sandbox --sandbox-name uat --production-username [email protected]
sfp server org register-sandbox --sandbox-name sit --production-username [email protected]
# 5. Create environments
sfp server environment create \
--repository myorg/salesforce-app \
--name Production \
--category release \
--branch main \
--description "Production environment" \
--targetusername [email protected]
sfp server environment create \
--repository myorg/salesforce-app \
--name UAT \
--category test \
--branch release/* \
--description "User Acceptance Testing" \
--targetusername [email protected]
sfp server environment create \
--repository myorg/salesforce-app \
--name SIT \
--category test \
--branch develop \
--description "System Integration Testing" \
--targetusername [email protected]Developer Access
# Developer authenticates with their GitHub account
sfp server auth login --provider github
# Developer can view environments
sfp server environment list --repository myorg/salesforce-app
# Developer accesses their assigned environment
sfp server environment get \
--name SIT \
--repository myorg/salesforce-app \
--auth-type accessToken \
--authenticate
# Developer can now work with the SIT environment
sf project deploy start --source-dir force-app --target-org SITCI/CD Service Account
# Admin creates application token for CI/CD
sfp server token create --name ci-deployment --expiry 90d
# Output: sfp_at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Store this in CI/CD secrets as SFP_SERVER_TOKENScenario 5: Handling Sandbox Refreshes
When a sandbox is refreshed, JIT authentication handles it automatically.
Before Refresh
# Verify current environment works
sfp server environment get \
--name UAT \
--repository myorg/salesforce-app \
--auth-type accessToken \
--authenticate
sfp org display --targetorg UATAfter Refresh
# Same command works - JIT re-authenticates via production
sfp server environment get \
--name UAT \
--repository myorg/salesforce-app \
--auth-type accessToken \
--authenticate
# New sandbox is ready to use
sf org display --target-org UATNo credential updates needed!
Scenario 6: Debugging Access Issues
Check Your Authentication
# View server auth status
sfp server auth display
# List available orgs
sfp server org list
# List environments
sfp server environment list --repository myorg/salesforce-appVerify Environment Details
# Get environment info (without authenticate to avoid credential issues)
sfp server environment get \
--name UAT \
--repository myorg/salesforce-app \
--jsonTest Credential Access
# Test if you can get credentials (requires owner/app role)
sfp server environment get \
--name UAT \
--repository myorg/salesforce-app \
--authenticate \
--auth-type accessToken
# If this fails with permission error, you may need elevated accessCommon Issues and Solutions
"Environment not found"
# Check exact name and repository
sfp server environment list --repository myorg/salesforce-app"Unauthorized"
# Re-authenticate
sfp server auth clear
sfp server auth login --provider github"Cannot retrieve credentials"
# Check your role - only owners and applications can get credentials
# Contact your admin for elevated accessQuick Reference
Environment Access Commands
Task
Command
List environments
sfp server environment list --repository REPO
Get environment info
sfp server environment get --name NAME --repository REPO
Authenticate to env
sfp server environment get --name NAME --repository REPO --authenticate
Lock environment
sfp server environment lock --name NAME --repository REPO --reason "..."
Unlock environment
sfp server environment unlock --name NAME --repository REPO --lock-ticket-id ID
Common Flags
Flag
Purpose
--authenticate
Also authenticate the org locally
--auth-type
accessToken (short-lived) or sfdxAuthUrl (long-lived)
--lock-ticket-id
Use with locked environments
--json
Output as JSON for scripting
Related Topics
Environments - Environment concepts
Environment Locking - Concurrency control
Server Authentication - Auth with sfp-server
Org Registration - Register orgs
Last updated