Deployment Readiness Check

When to Use This Skill

Use this skill before deploying Salesforce metadata to production (or higher environments) to:

• Validate metadata quality and completeness
• Check test coverage meets organizational standards
• Verify security settings and permissions
• Identify configuration issues before deployment
• Generate deployment documentation

Prerequisites

• Salesforce CLI installed and authenticated to target org
• jq command-line JSON processor installed
• Bash shell (Linux, macOS, or WSL on Windows)
• Source metadata in SFDX project format

Step 1: Run Metadata Validation

Execute the validation script to check for common metadata issues:

bash scripts/check_metadata.sh

The script validates:

• Metadata format - Ensures all XML is well-formed
• API versions - Checks for outdated API versions
• Deprecated features - Identifies deprecated components
• Naming conventions - Validates standard naming patterns
• File completeness - Ensures meta.xml files are present

Review the output for any warnings or errors before proceeding.

Step 2: Verify Test Coverage

Check that your Apex test coverage meets organizational standards:

# Run all tests and generate coverage report
sf apex test run --test-level RunLocalTests --result-format human --code-coverage --wait 10

# Check coverage percentage
sf apex get test --test-run-id <test-run-id> --code-coverage --result-format json | jq '.summary.testRunCoverage'

Minimum requirements:

• Overall org coverage: ≥75% (Salesforce minimum)
• Individual class coverage: ≥75% (recommended)
• No classes with 0% coverage

If coverage is below threshold: 1. Identify uncovered classes using the coverage report 2. Add test methods to increase coverage 3. Rerun tests until requirements are met

Step 3: Security and Permissions Review

Review security settings and permissions to ensure proper access controls:

1. Profile and Permission Set Review

• Check that custom profiles/permission sets follow least-privilege principle
• Verify admin permissions are not granted to standard users
• Ensure sensitive objects have appropriate FLS

2. Sharing Rules and OWD

• Review Organization-Wide Defaults are appropriate
• Validate sharing rules grant necessary access without over-sharing
• Check for public groups with excessive membership

3. API Access

• Verify Connected Apps have appropriate scopes
• Check Named Credentials use secure authentication
• Review Remote Site Settings are necessary

Consult the security checklist reference for detailed guidance.

Step 4: Configuration Validation

Verify configuration settings are deployment-ready:

# Check for hardcoded URLs or IDs
grep -r "https://.*\.salesforce\.com" force-app/main/default/
grep -r "[a-zA-Z0-9]{15,18}" force-app/main/default/ | grep -v "meta.xml"

# Validate Custom Settings and Custom Metadata
sf project retrieve start --metadata CustomObject:*__c

Configuration checklist:

• [ ] No hardcoded production URLs in code
• [ ] No hardcoded record IDs
• [ ] Custom Settings configured correctly for target org
• [ ] Custom Metadata Types populated appropriately
• [ ] Email templates reference correct org email
• [ ] Reports and Dashboards folders have correct permissions

Step 5: Review Dependencies

Check for dependency conflicts or missing components:

# Generate dependency report
sf project deploy validate --manifest package.xml --test-level RunLocalTests --verbose

# Check for missing dependencies
grep -i "error.*component" deployment_log.txt

Common dependency issues:

• Missing Custom Fields referenced in code
• Validation Rules referencing deleted fields
• Workflows or Process Builders using deprecated actions
• Lightning Components with missing design resources

See dependency troubleshooting guide for solutions.

Step 6: Generate Deployment Checklist

Use the deployment checklist template to document your release:

cp assets/deployment_checklist.md deployment_checklist_$(date +%Y%m%d).md

Fill out the checklist with:

• [ ] Deployment date and time window
• [ ] Components being deployed (attach package.xml)
• [ ] Test execution results and coverage
• [ ] Backup verification (data and metadata)
• [ ] Rollback procedure documented
• [ ] Stakeholders notified
• [ ] Post-deployment validation steps
• [ ] Monitoring plan for 24-48 hours

Step 7: Execute Pre-Deployment Validation

Run a validation-only deployment to catch issues before actual deployment:

# Validate deployment without committing
sf project deploy validate \
  --manifest package.xml \
  --test-level RunLocalTests \
  --verbose

# Save the validation ID for quick deploy
sf project deploy start --use-most-recent-validation --async

Benefits of validation:

• Tests run in production environment
• Identifies environment-specific issues
• Generates Quick Deploy ID for faster deployment
• No changes committed until you confirm

Review validation results and address any failures before scheduling deployment.

Step 8: Prepare Rollback Plan

Document rollback procedures before deploying:

1. Backup current state

   sf project retrieve start --manifest package.xml --target-org production
   git tag pre-deployment-$(date +%Y%m%d) && git push --tags

2. Test rollback procedure in sandbox:

• Deploy previous version of metadata
• Verify functionality is restored
• Document any data cleanup required

3. Establish rollback criteria:

• Critical bugs found within 2 hours
• Core functionality broken
• Performance degradation >50%
• Data integrity issues

See rollback procedures reference for detailed steps.

Post-Deployment Validation

After successful deployment, verify the release:

1. Smoke tests - Execute critical user workflows 2. Monitor logs - Check debug logs for errors (24-48 hours) 3. Query test data - Verify triggers and automation work correctly 4. User acceptance - Confirm with stakeholders functionality works 5. Performance check - Review governor limit usage in logs

Common Issues and Solutions

Issue: Test Coverage Drops Below 75%

Cause: New Apex classes added without sufficient tests.

Solution: 1. Run sf apex test run --code-coverage to identify gaps 2. Add test methods covering uncovered lines 3. Revalidate coverage

Issue: Validation Fails with "Component Not Found"

Cause: Missing dependency in package.xml.

Solution: 1. Review error message for missing component 2. Add component to package.xml 3. Retrieve component from source org if needed 4. Revalidate

Issue: Permission Errors After Deployment

Cause: FLS or object permissions not deployed correctly.

Solution: 1. Verify profiles/permission sets are in package.xml 2. Check that CustomObject metadata includes field permissions 3. Deploy profiles separately if needed 4. Use Permission Set Groups for complex permission hierarchies

Best Practices

1. Always validate before deploying - Never deploy directly to production without validation 2. Run full test suite - Use RunLocalTests, not NoTestRun 3. Deploy during maintenance windows - Minimize impact on users 4. Communicate with stakeholders - Notify before, during, and after deployment 5. Monitor post-deployment - Watch logs and user feedback for 24-48 hours 6. Document everything - Maintain deployment logs and decisions 7. Use version control tags - Tag releases for easy rollback

References

• Security Checklist - Detailed security review steps
• Dependency Resolution Guide - Solve dependency conflicts
• Rollback Procedures - Step-by-step rollback guide
• Deployment Checklist Template - Reusable checklist

Automation Opportunities

Consider automating this skill:

• CI/CD Integration - Run validation script in pipeline
• Scheduled Coverage Checks - Monitor test coverage daily
• Auto-generated Documentation - Create deployment notes from package.xml
• Slack/Email Notifications - Alert team of deployment status

Salesforce Deployment Checklist

Deployment Date: _________________ Deployment Time Window: _________ to _________ Environment: ☐ Production ☐ Sandbox ☐ UAT Deployment Lead: _________________ Release Version: _________________

---

Pre-Deployment

1. Code & Configuration Review

• [ ] All code reviewed and approved via pull request
• [ ] Code follows organizational coding standards
• [ ] No debugging statements or console.logs in production code
• [ ] API versions are current (API 56.0+)
• [ ] Hard-coded IDs/URLs removed (use Custom Settings or Custom Metadata)
• [ ] Comments and documentation are up-to-date

2. Testing

• [ ] All unit tests pass locally
• [ ] Test coverage meets minimum requirements (≥75% org-wide)
• [ ] Integration tests executed successfully
• [ ] User acceptance testing (UAT) completed
• [ ] Regression testing performed for existing features
• [ ] Performance testing validates no degradation

Test Results:

• Total classes: _____
• Test coverage: _____%
• Failed tests: _____
• Test run ID: _________________

3. Security Review

• [ ] Profile/permission set changes reviewed
• [ ] Field-level security validated
• [ ] Sharing rules appropriate for data sensitivity
• [ ] No admin permissions granted to standard users
• [ ] Connected Apps use appropriate OAuth scopes
• [ ] Named Credentials use secure authentication
• [ ] Sensitive data is encrypted or masked

4. Dependencies

• [ ] All metadata dependencies identified
• [ ] Missing components added to package.xml
• [ ] External system dependencies documented
• [ ] API integrations tested in target environment
• [ ] Third-party packages compatible with deployment

5. Backup & Rollback

• [ ] Pre-deployment backup completed
• Metadata backup: ☐ Yes ☐ N/A
• Data backup: ☐ Yes ☐ N/A
• Backup location: _________________
• [ ] Rollback procedure documented and tested
• [ ] Rollback criteria defined
• [ ] Emergency contacts list current

6. Documentation

• [ ] Release notes prepared
• [ ] Deployment guide created
• [ ] User training materials ready (if applicable)
• [ ] Help documentation updated
• [ ] Known issues documented
• [ ] FAQ prepared for support team

7. Communication

• [ ] Stakeholders notified of deployment schedule
• [ ] Users notified of system downtime (if applicable)
• [ ] Support team briefed on changes
• [ ] Change advisory board approval obtained
• [ ] Post-deployment communication template ready

8. Validation

• [ ] Validation deployment successful in production
• [ ] Quick Deploy ID obtained: _________________
• [ ] Validation results reviewed and approved
• [ ] All deployment warnings addressed

Validation Command:

sf project deploy validate --manifest package.xml --test-level RunLocalTests --verbose

---

Deployment Execution

9. Pre-Deployment Actions

• [ ] Announced maintenance window to users
• [ ] Disabled scheduled jobs/batch processes (if required)
• Jobs disabled: _________________
• [ ] Created deployment tag in git: _________________
• [ ] Verified target org connectivity
• [ ] Team on standby for deployment

10. Deployment

Deployment Start Time: _________

• [ ] Deployment initiated via validated package or change set
• [ ] Deployment progress monitored
• [ ] Test execution in progress
• [ ] Any deployment errors addressed immediately

Deployment Command:

sf project deploy start --use-most-recent-validation
# OR
sf project deploy start --manifest package.xml --test-level RunLocalTests

Deployment ID: _________________

Deployment End Time: _________

Duration: _________ minutes

11. Post-Deployment Verification

• [ ] Deployment completed successfully
• [ ] All tests passed in production
• [ ] Deployment results reviewed (no warnings/errors)
• [ ] Smoke tests executed successfully
• [ ] Critical user workflows verified:
• [ ] Workflow 1: _________________
• [ ] Workflow 2: _________________
• [ ] Workflow 3: _________________
• [ ] Re-enabled scheduled jobs/batch processes
• [ ] Debug logs show no new errors

12. Post-Deployment Actions

• [ ] Stakeholders notified of successful deployment
• [ ] Users notified system is available
• [ ] Release notes published
• [ ] Support team provided with deployment summary
• [ ] Monitoring dashboard reviewed

---

Post-Deployment Monitoring (24-48 Hours)

13. System Monitoring

• [ ] Day 1 - Monitor debug logs for errors
• Errors found: ☐ Yes ☐ No
• If yes, describe: _________________
• [ ] Day 1 - Review governor limit usage
• Limits exceeded: ☐ Yes ☐ No
• [ ] Day 1 - Check user-reported issues
• Issues reported: ☐ Yes ☐ No
• [ ] Day 2 - Confirm automation working correctly
• [ ] Day 2 - Validate data integrity
• [ ] Day 2 - Review performance metrics

14. User Acceptance

• [ ] Key users confirmed functionality works
• [ ] No critical bugs reported
• [ ] User feedback collected
• [ ] Support tickets categorized by severity

Feedback Summary: _________________

---

Rollback (If Required)

Rollback Decision: ☐ Yes ☐ No

Reason: _________________

• [ ] Stakeholder approval for rollback obtained
• [ ] Users notified of rollback
• [ ] Rollback procedure executed
• [ ] Rollback verified successful
• [ ] Post-rollback communication sent

Rollback Time: _________

---

Deployment Summary

Components Deployed

Total Components: _____

Deployment Metrics

• Validation time: _________ minutes
• Deployment time: _________ minutes
• Test execution time: _________ minutes
• Total elapsed time: _________ minutes
• Downtime (if any): _________ minutes

Issues Encountered

Total Issues: _____

---

Sign-Off

Deployment Team

Deployment Lead: _________________ Date: _________ Developer(s): _________________ Date: _________ QA Lead: _________________ Date: _________ DevOps Engineer: _________________ Date: _________

Stakeholders

Product Owner: _________________ Date: _________ Business Analyst: _________________ Date: _________ Release Manager: _________________ Date: _________

---

Post-Deployment Review

Review Date: _________________

What Went Well

1. _________________ 2. _________________ 3. _________________

What Could Be Improved

1. _________________ 2. _________________ 3. _________________

Action Items

• [ ] Action: _________________ Owner: _________ Due: _________
• [ ] Action: _________________ Owner: _________ Due: _________
• [ ] Action: _________________ Owner: _________ Due: _________

---

Attachments

• [ ] package.xml
• [ ] Test results report
• [ ] Deployment log
• [ ] Release notes
• [ ] Rollback procedure (if executed)
• [ ] Post-deployment monitoring reports

Storage Location: _________________

---

Notes: _________________ _________________ _________________

Rollback Procedures

This guide provides step-by-step instructions for rolling back a Salesforce deployment if issues are discovered after release.

When to Rollback

Execute a rollback when:

• Critical functionality is broken and cannot be hotfixed quickly
• Data integrity issues are discovered
• Performance degradation exceeds 50% of baseline
• Security vulnerabilities are introduced
• Stakeholder approval to rollback is obtained

Do NOT rollback for:

• Minor UI issues that don't impact functionality
• Issues that can be hotfixed in < 2 hours
• Edge cases affecting < 5% of users
• Cosmetic problems

Pre-Rollback Checklist

Before initiating rollback:

• [ ] Confirm the issue severity justifies rollback
• [ ] Obtain stakeholder approval
• [ ] Notify all users of upcoming rollback
• [ ] Backup current production state (post-deployment)
• [ ] Verify pre-deployment backup is available
• [ ] Review rollback plan with team
• [ ] Prepare communication for completion

Rollback Methods

Method 1: Redeploy Previous Version (Recommended)

Best for: Metadata-only deployments with no data changes.

Steps:

1. Retrieve pre-deployment state from version control:

   git checkout pre-deployment-YYYYMMDD

2. Validate rollback deployment:

   sf project deploy validate \
     --manifest manifest/package.xml \
     --test-level RunLocalTests \
     --target-org production

3. Deploy previous version:

   sf project deploy start \
     --manifest manifest/package.xml \
     --test-level RunLocalTests \
     --target-org production

4. Verify rollback:

• Test critical user flows
• Check for errors in debug logs
• Confirm with stakeholders

Timeline: 30-60 minutes

Method 2: Selective Component Rollback

Best for: When only specific components are problematic.

Steps:

1. Identify problematic components:

• Review error logs
• Isolate failing functionality
• List components to rollback

2. Create targeted package.xml:

   <?xml version="1.0" encoding="UTF-8"?>
   <Package xmlns="http://soap.sforce.com/2006/04/metadata">
       <types>
           <members>ProblematicClass</members>
           <name>ApexClass</name>
       </types>
       <version>59.0</version>
   </Package>

3. Retrieve previous version of components:

   git show pre-deployment-YYYYMMDD:force-app/main/default/classes/ProblematicClass.cls > temp/ProblematicClass.cls

4. Deploy only those components:

   sf project deploy start \
     --manifest rollback-package.xml \
     --target-org production

Timeline: 15-30 minutes

Method 3: Destructive Changes

Best for: When new components must be removed entirely.

Steps:

1. Create destructiveChanges.xml:

   <?xml version="1.0" encoding="UTF-8"?>
   <Package xmlns="http://soap.sforce.com/2006/04/metadata">
       <types>
           <members>NewComponentToDelete</members>
           <name>ApexClass</name>
       </types>
       <version>59.0</version>
   </Package>

2. Create empty package.xml:

   <?xml version="1.0" encoding="UTF-8"?>
   <Package xmlns="http://soap.sforce.com/2006/04/metadata">
       <version>59.0</version>
   </Package>

3. Deploy destructive changes:

   sf project deploy start \
     --manifest package.xml \
     --pre-destructive-changes destructiveChanges.xml \
     --test-level RunLocalTests \
     --target-org production

4. Verify deletion:

   sf org list metadata --metadata-type ApexClass --target-org production

Timeline: 20-40 minutes

Data Rollback Considerations

If the deployment included data changes:

Option A: Restore from Backup

1. Locate pre-deployment data backup:

• Data Export Service snapshot
• Backup tool (OwnBackup, Spanning, etc.)
• Manual CSV exports

2. Restore data:

   sf data import tree --plan data-backup/data-plan.json --target-org production

3. Validate data integrity:

• Run data quality checks
• Verify record counts
• Check relationships

Timeline: 1-4 hours (depending on data volume)

Option B: Reverse Data Changes (Scripted)

1. Identify affected records:

   sf data query --query "SELECT Id FROM Account WHERE LastModifiedDate >= YESTERDAY"

2. Apply reverse operations:

• Create Apex script to reverse changes
• Test in sandbox first
• Execute in production

Timeline: 2-6 hours

Post-Rollback Steps

After rollback is complete:

1. Verify Functionality:

• [ ] Execute smoke tests
• [ ] Confirm critical workflows work
• [ ] Check automation (triggers, flows) operates correctly
• [ ] Review debug logs for errors

2. Communication:

• [ ] Notify users rollback is complete
• [ ] Send post-mortem summary to stakeholders
• [ ] Update status page / internal wiki

3. Root Cause Analysis:

• [ ] Document what went wrong
• [ ] Identify why issues weren't caught pre-deployment
• [ ] Update deployment checklist to prevent recurrence
• [ ] Schedule retrospective with team

4. Next Steps:

• [ ] Fix issues in development environment
• [ ] Add test cases to catch similar issues
• [ ] Re-validate deployment in sandbox
• [ ] Schedule new deployment with fixes

Emergency Contacts

Production Issues:

• On-call DevOps: [contact info]
• Salesforce Support: [premier support phone]
• Release Manager: [contact info]

Stakeholder Notifications:

• Product Owner: [contact info]
• Business Analyst: [contact info]
• Executive Sponsor: [contact info]

Rollback Decision Matrix

Lessons Learned Template

After each rollback, document lessons learned:

# Rollback Post-Mortem: [Date]

## Deployment Summary
- Deployment date/time: [timestamp]
- Components deployed: [list]
- Rollback date/time: [timestamp]
- Rollback method used: [method]

## Issue Description
[Describe what went wrong]

## Root Cause
[Why did the issue occur?]

## Detection
- How was the issue discovered?
- How long after deployment?
- Who reported it?

## Impact
- Number of users affected: [count]
- Business processes impacted: [list]
- Duration of impact: [timespan]

## Resolution
- Rollback timeline: [start - end]
- Additional fixes required: [list]

## Prevention
- What tests would have caught this?
- Process improvements needed:
- Deployment checklist updates:

## Action Items
- [ ] [Action item with owner]
- [ ] [Action item with owner]

Best Practices

1. Practice rollbacks in sandbox - Don't wait for an emergency to learn the process 2. Maintain detailed backups - Automate metadata and data backups before every deployment 3. Use version control tags - Tag every production deployment for easy identification 4. Document everything - Keep a deployment log with timestamps and decisions 5. Communicate proactively - Keep stakeholders informed throughout the process 6. Set time limits - If rollback takes >2 hours, consider alternative approaches 7. Test the rollback - Validate in sandbox that the rollback process works

Rollback Scripts Repository

Keep commonly-used rollback scripts in version control:

scripts/rollback/
├── rollback-apex.sh          # Rollback Apex classes
├── rollback-lwc.sh           # Rollback Lightning Web Components
├── rollback-flows.sh         # Rollback flows and processes
├── rollback-data.sh          # Restore data from backup
└── verify-rollback.sh        # Post-rollback verification

Testing Rollback Procedures

Quarterly rollback drill: 1. Deploy a test change to sandbox 2. Wait 1 hour 3. Execute full rollback procedure 4. Time the process 5. Document any issues 6. Update procedures as needed

This ensures the team is prepared when a real rollback is needed.