How to Write a Sandbox Refresh Runbook Your Team Will Follow

A sandbox refresh runbook your team will follow is short, lives next to your code, and gives every step an owner, a time estimate and a check that proves it is done. Most refresh docs fail because they are long wiki pages nobody owns. Write yours as a four-phase checklist, automate the steps people skip, and rehearse it once before you rely on it.

What is a sandbox refresh runbook?

A sandbox refresh runbook is the step-by-step procedure your team runs every time a Salesforce sandbox is refreshed from production: what to save before, what to restore after, who does each step and how you know it worked. It is not your sandbox strategy, which decides which sandboxes exist and why. The runbook is the part people execute on refresh morning.

Why do teams ignore refresh runbooks?

• No owner per step. When the team restores the integrations, nobody does.
• No definition of done. Reconfigure integrations cannot be checked. A test callout through the named credential returns 200 can.
• It lives in the wrong place. A wiki page drifts away from the org. A Markdown file in the repo gets reviewed when the org changes.
• Too many manual steps. Every manual step is one someone will skip under time pressure.

How often can you refresh each sandbox type?

Salesforce caps your cadence, so put the limits at the top of the runbook. According to Salesforce Ben's sandbox guide:

• Developer and Developer Pro: once per day, metadata only.
• Partial Copy: every five days, metadata plus a portion of your data.
• Full: every 29 days, all production metadata and data.

A botched Full refresh can cost you a month, so that runbook deserves the most rigor.

What goes in each phase of the runbook?

Write every step in the same format: step | owner | automated? | minutes | done when. Then group the steps into four phases.

1. Before the refresh

• Announce the window to developers, QA and business testers, and get an acknowledgement.
• Commit or deploy every in-flight change to version control. A refresh overwrites the sandbox, and anything not in Git is gone.
• Export configuration stored as data, such as the settings records some AppExchange packages keep outside metadata.
• List the integration endpoints, named credentials and connected apps you will need to repoint.

2. During the refresh

• Confirm production is stable, not halfway through a release.
• Specify your post-copy Apex class when you start the refresh, so automation runs without anyone remembering it.
• Record the start time and who triggered it.

3. After the refresh

• Keep email deliverability on System email only, the default for new and refreshed sandboxes according to Apex Hours, until data is masked.
• Remove the .invalid suffix only for users who need sandbox email. Salesforce appends it to user email addresses on every refresh or clone, as its help article explains.
• Mask or delete personal data before you widen access.
• Repoint integrations to their sandbox endpoints and re-authenticate.
• Redeploy work that is ahead of production from version control, then reload test data.

4. Validate and hand over

• Run a smoke test: log in as a tester, run one key flow, make one test callout.
• Run your Apex tests, or at least the subset that covers your integrations.
• Post a sandbox-ready message with known issues, and fix anything that broke in the runbook itself.

Which refresh steps should you automate first?

Automate the steps that are frequent, error-prone and boring. Salesforce's SandboxPostCopy interface lets you write an Apex class that runs automatically when the sandbox is created, and Salto's refresh best practices list masking email addresses and updating custom settings and custom metadata as typical uses. Good first candidates:

1. Masking personal data on contacts and leads.
2. Resetting custom settings and endpoint configuration to sandbox values.
3. Restoring email for the small group of users who need it.
4. Reloading baseline test data. Our guide on how to seed a Salesforce sandbox with realistic data covers the options.

Keep the class idempotent and log what it changed, so a failed run can be repeated safely.

How does the runbook fit into your release pipeline?

A refresh resets a sandbox to production, so anything between that sandbox and production disappears unless your pipeline puts it back. Two habits stop the loss. First, treat Git as the source of truth, so work in progress is redeployed, not rebuilt. Second, set up back-promotion in your Salesforce DevOps pipeline so production hotfixes flow down to lower environments between refreshes. After the refresh, run the same checks you run on every pull request. Our guide to Salesforce test automation in CI splits what to run per pull request from what to run nightly.

If redeploying after every refresh is still a manual afternoon, a DevOps platform takes most of it off your plate. Serpent's free Essentials plan includes delta deployments and one-click rollback; compare plans on Serpent pricing.

How do you get the team to actually follow it?

• Keep each phase to one screen and link out for detail.
• Store the runbook in the repo and review changes to it like code.
• Rehearse on a Developer sandbox, which you can refresh daily, before the next Full refresh.
• Update it the same day something breaks. A runbook that is wrong once gets ignored for good.
• Name a backup owner for every step.

For more practical guides like this one, browse the SF Guides library.

FAQ

How long should a sandbox refresh runbook be?

Short enough to fit one screen per phase. Keep the runbook as the checklist and put the detail in linked docs.

What is SandboxPostCopy used for?

It is an Apex interface for a class that runs automatically when a sandbox is created, typically to mask data and reset settings.

Why do user emails end in .invalid after a refresh?

Salesforce appends .invalid so production users do not get email from the sandbox. Remove it only for users who need sandbox email.

How often can you refresh a Full sandbox?

Once every 29 days. Partial Copy sandboxes can be refreshed every five days and Developer sandboxes daily.