🗑️ SFDX Delete Scratch Org

This repository implements a simple GitHub composite action for deleting a Salesforce scratch org. It is the natural counterpart to sfdx-create-scratch-org and is typically used as a cleanup step so that scratch orgs created during a CI run are released again, even if previous steps fail.

Usage

The action pairs nicely with the username output of the create action and an if: always() condition to guarantee cleanup:

# Least-privilege token: the workflow only reads the repository and talks to
# Salesforce via the CLI, it never writes back to GitHub.
permissions:
  contents: read

jobs:
  scratch-org-ci:
    name: Scratch Org CI
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7.0.1
        with:
          persist-credentials: false # the GITHUB_TOKEN is not needed after the checkout - don't leave it in .git/config

      - name: Install SF CLI
        uses: svierk/sfdx-cli-setup@v1.1.3

      - name: Authorize DevHub
        uses: svierk/sfdx-login@v1.4.2
        with:
          sfdx-url: ${{ secrets.SFDX_AUTH_URL }}
          set-default-dev-hub: true
          alias: devhub

      - name: Create Scratch Org
        id: scratch
        uses: svierk/sfdx-create-scratch-org@v1.3.2
        with:
          target-dev-hub: devhub
          definition-file: config/project-scratch-def.json
          duration-days: 1

      - name: Deploy Metadata
        uses: svierk/sfdx-deploy@v1.2.2
        with:
          source-dir: force-app
          target-org: ${{ steps.scratch.outputs.username }}
          destructive-changes: false # a fresh scratch org has nothing to delete

      # ... run tests, etc. ...

      - name: Delete Scratch Org
        if: always() # release the org even when a previous step failed
        uses: svierk/sfdx-delete-scratch-org@v1.1.2
        with:
          target-org: ${{ steps.scratch.outputs.username }}

A few conventions the example follows and that are worth keeping in your own workflows:

• Pin every uses: to an exact release tag (@v1.1.2), not to a branch like @main and not to a floating major like @v1. An update then becomes an explicit, reviewable change - ideally raised automatically by Dependabot.
• Declare permissions: at workflow or job level. Creating and deleting a scratch org needs nothing but contents: read.
• Keep secrets in secrets/env. Hand them to an action via its inputs. Wherever you do fall back to a run: script, pass dynamic values in through env: instead of interpolating ${{ ... }} directly into the shell command.

The following actions were also used in the example on this page:

• SFDX CLI Setup | Installs the Salesforce CLI and related plugins
• SFDX Login | Handles Salesforce login using a SFDX auth URL or a JSON web token (JWT)
• SFDX Create Scratch Org | Creates the scratch org that this action deletes again - the natural counterpart of this action
• SFDX Deploy | Deploys Salesforce metadata to a target org

Inputs

Name	Required	Default	Description
target-org	no		Username or alias of the scratch org to delete. Not required if the default org is set.
step-summary	no	true	Write a result section to the GitHub Actions job summary. Set to false to avoid collisions with a custom workflow summary.

The action always runs with --no-prompt, so it never blocks the pipeline waiting for confirmation.

On success the action logs a confirmation with the deleted org and, unless step-summary is set to false, adds an entry to the GitHub Step Summary, so the cleanup result is visible directly in the run overview.

References

The deletion option supported by this GitHub composite action can be found in the Salesforce CLI Command Reference here:

• org delete scratch

Releases

Latest release notes can be found on the release page.

License

The scripts and documentation in this project are released under the MIT License.

---

➡️ Full source & releases: svierk/sfdx-delete-scratch-org