Scratch Org Management

Scratch Org Management

This skill activates when you need to design the shape of a scratch org (definition file), manage allocation limits across a team or CI system, troubleshoot provisioning failures, or automate scratch org lifecycle via the Dev Hub API. It assumes Dev Hub is already enabled; for basic CLI commands and first-time setup see sf-cli-and-sfdx-essentials.

Before Starting

Gather this context before working on anything in this domain:

• What is the Dev Hub edition? The edition determines hard daily and active limits (see Core Concepts). Hitting the active limit is the most common cause of org create scratch failures.
• What features does the target environment need? Every feature the org under test depends on must be declared in the definition file — or provisioned via Org Shape — or tests will behave differently than in a real org.
• Is this for a single developer, a team, or CI? Teams and CI pipelines exhaust limits faster and require a discipline around explicit org deletion and alias conventions.

Core Concepts

1. The Scratch Org Definition File

The definition file (config/project-scratch-def.json) is a JSON blueprint that tells Dev Hub exactly what kind of scratch org to provision. It is not part of sfdx-project.json; it is a standalone file in the config/ directory by convention.

Minimal required field:

{
  "edition": "Developer"
}

Full annotated example:

{
  "edition": "Enterprise",
  "description": "Feature branch — Communities + API",
  "duration": 7,
  "hasSampleData": false,
  "language": "en_US",
  "country": "US",
  "features": ["Communities", "LightningServiceConsole"],
  "settings": {
    "lightningExperienceSettings": {
      "enableS1DesktopEnabled": true
    },
    "mobileSettings": {
      "enableS1EncryptedStoragePref2": false
    }
  }
}

Key fields:

2. Edition Types and What They Control

The edition field sets the base feature set and license model. Choose the edition that most closely matches the org your code will be deployed to in production or the target packaging environment.

Do not use Developer edition if the production org is Enterprise and you need to test features that require Enterprise licensing — the org will provision successfully but will be missing feature flags.

3. Allocation Limits by Dev Hub Edition

Limits are enforced at the Dev Hub org level, not per user. All users sharing a Dev Hub share the same pool.

Source: Salesforce DX Developer Guide — Supported Scratch Org Editions and Allocations

Expiration: Default is 7 days. Max is 30 days. Expired orgs are automatically deleted by Salesforce along with their ActiveScratchOrg records. Specify --duration-days at creation time; you cannot extend a scratch org after it is created.

4. Dev Hub Objects for Automation

Two standard objects in the Dev Hub org expose scratch org state for SOQL queries and automation:

• ActiveScratchOrg — one record per currently active scratch org. Deleting this record deletes the scratch org. The ExpirationDate field is queryable.
• ScratchOrgInfo — one record per scratch org creation request, both active and historical. Use this for audit trails, CI dashboards, and to detect orgs approaching expiry.

SELECT Id, OrgName, ExpirationDate, CreatedBy.Name
FROM ActiveScratchOrg
WHERE ExpirationDate <= NEXT_N_DAYS:2
ORDER BY ExpirationDate ASC

5. Org Shape

Org Shape captures the edition, features, settings, and licenses of a specific source org (typically production or a staging sandbox) and uses them as the blueprint for scratch org creation — without manually maintaining a definition file for every feature toggle. Org Shape is available for Enterprise and above Dev Hubs.

When to prefer Org Shape over a hand-maintained definition file:

• Production has many enabled features that are hard to enumerate manually
• You want scratch orgs to automatically reflect new features enabled in production
• The team's definition file drifts from production and causes "works in scratch, breaks in prod" failures

When to keep a definition file:

• You want a deliberately minimal or controlled environment (e.g., packaging)
• You need portability across multiple source orgs

Common Patterns

Mode 1: Create a Scratch Org from a Definition File

When to use: Standard feature branch development; new team member onboarding; CI jobs.

# Create org from definition file, set as default, expire in 14 days
sf org create scratch \
  --definition-file config/project-scratch-def.json \
  --alias feature-myfeature \
  --duration-days 14 \
  --set-default \
  --target-dev-hub MyDevHub

# Push source to the new org
sf project deploy start

# Open the org in a browser
sf org open --target-org feature-myfeature

# When done — explicitly delete to free allocation
sf org delete scratch --target-org feature-myfeature --no-prompt

Mode 2: Audit and Manage Active Org Pool from Dev Hub

When to use: Team lead or CI admin needs to reclaim allocations; pre-flight check before a CI run; regular hygiene.

# List all orgs known to the local CLI
sf org list --all

# From inside the Dev Hub org, query active orgs
sf data query \
  --query "SELECT OrgName, ExpirationDate, CreatedBy.Name FROM ActiveScratchOrg ORDER BY ExpirationDate ASC" \
  --target-org MyDevHub

# Delete a specific scratch org by alias
sf org delete scratch --target-org stale-org-alias --no-prompt

Mode 3: Automate in CI (GitHub Actions pattern)

When to use: Pull request pipelines that need a fresh org per run and must release it when done.

# .github/workflows/ci.yml (relevant steps)
- name: Authenticate Dev Hub
  run: sf org login jwt --client-id ${{ secrets.SF_CLIENT_ID }} \
       --jwt-key-file server.key \
       --username ${{ secrets.SF_USERNAME }} \
       --alias DevHub --set-default-dev-hub

- name: Create scratch org
  run: sf org create scratch \
       --definition-file config/project-scratch-def.json \
       --alias ci-org --duration-days 1 \
       --target-dev-hub DevHub

- name: Deploy and test
  run: |
    sf project deploy start --target-org ci-org
    sf apex run test --target-org ci-org --result-format tap --code-coverage

- name: Delete scratch org
  if: always()
  run: sf org delete scratch --target-org ci-org --no-prompt

The if: always() guard ensures the org is deleted even when prior steps fail, preventing allocation leaks.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking work in this area complete:

• edition in definition file matches the target deployment environment
• All required features are declared; no relying on defaults that differ across editions
• duration is appropriate: CI orgs use 1 day, developer orgs use no more than 14 days
• CI pipeline includes an unconditional delete step (if: always())
• Team is not sharing a Developer Edition Dev Hub for multi-person CI (only 3 active orgs)
• hasSampleData: false unless test data is explicitly needed
• Org Shape source org is specified when using Org Shape
• ScratchOrgInfo records reviewed in Dev Hub after any provisioning failure

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Daily limit is a rolling 24-hour window, not a midnight reset — The daily scratch org limit resets on Salesforce's rolling 24-hour window tied to the Dev Hub instance, not the user's local midnight. Teams scheduling CI jobs at midnight may still be within the previous window's count.

2. orgPreferences is deprecated and silently drops settings — Definition files using the old orgPreferences format provision successfully, but some settings are silently ignored. The correct format is settings using Metadata API setting objects. A definition file that "worked before" may be missing settings on newer API versions without any error.

3. Scratch org expiration cannot be extended after creation — The --duration-days flag is set once at creation time. There is no extension command. If work is in progress on an expiring org, the only recovery path is to push source, create a new org, and re-pull — or extract the org's metadata before expiry.

4. Deleting from Active Scratch Orgs list does NOT delete the ScratchOrgInfo record — ScratchOrgInfo is a permanent audit record of every creation request. Only ActiveScratchOrg is deleted (and the org freed). This confuses practitioners expecting both records to be cleaned up, but it is correct behavior.

5. hasSampleData: true dramatically slows provisioning — Sample data injection adds 3–5 minutes to scratch org creation. In CI with parallel jobs, this compounds significantly. Disable it unless tests depend on standard sample objects.

Output Artifacts

Related Skills

• sf-cli-and-sfdx-essentials — First-time CLI setup, Dev Hub enablement, basic push/pull/open commands; use this when the user is new to SFDX
• cicd-pipeline-setup — Full CI/CD pipeline configuration beyond the scratch org lifecycle step
• source-tracking-and-deploy — Deep dive on source tracking behavior, delta deploys, and retrieve conflicts