forcedotcom/sf-skills / plugins/builder/dx-packaging/skills/dx-packaging-push-upgrade-configure
dx-packaging-push-upgrade-configure
VerifiedUse this skill to plan, schedule, and monitor Salesforce package push upgrades from a Dev Hub. Finds subscriber orgs via the PackageSubscriber object, resolves and validates the target package version, builds a best-practice batched schedule (pilot sandboxes, then staggered off-peak production batches), generates the per-batch org-ID CSV, and — only after explicit confirmation — runs the sf package push-upgrade CLI commands, then monitors PackagePushRequest, PackagePushJob, and PackagePushError. Supports 2GP managed, unlocked, and 1GP-to-2GP push migrations. TRIGGER when the user wants to push a package upgrade to subscribers, find who has a package installed and at what version, batch a rollout by region, or schedule, monitor, or abort a push upgrade. DO NOT TRIGGER for post-install configuration of an installed package (use dx-pkg-post-install-configure), creating or versioning a package, or installing a package into one org.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.3 KB |
| SKILL.md | skill md | 21.4 KB |
| references/best-practices.md | markdown | 3.2 KB |
| references/cli-reference.md | markdown | 7.5 KB |
| references/objects.md | markdown | 4.6 KB |
| references/soql-recipes.md | markdown | 4.8 KB |
references/best-practices.md
View on GitHub# Push upgrade best practices
Source: Salesforce "Push Upgrade Best Practices" (2GP dev guide). Push upgrades change a package in a
customer's org **without their action** — poor planning "can result in significant customer
satisfaction issues," and buggy upgrades can affect **data**, not just metadata.
---
## Timing & scheduling
- Give customers an **upgrade timeline** up front: when and how often you'll push.
- **Avoid disruptive windows**: month-end, quarter-end, year-end, audit cycles, and any period when the
customer lacks staff to verify.
- Schedule for the customer's **off-peak hours** (late evening/night). Account for time zones —
**group orgs by time zone** (use `InstanceName` as a proxy) and schedule each group separately.
`--start-time` is **UTC**; convert deliberately.
- Steer clear of **Salesforce maintenance windows**, and ideally **wait 3–4 weeks after a major
Salesforce release** before pushing major upgrades.
## Testing (a higher bar than customer-pulled upgrades)
- Push to **your own test orgs first**, then log in and verify.
- Where possible, push to **customer sandboxes first** and allow **a week or more** to test, validate,
and fix before touching production.
- Add an **Apex test-on-install** for basic sanity checks during the upgrade.
## Staggering / batching
- **Don't push to everyone at once.** Staggering protects support capacity and catches issues early.
- Start with **small production batches** (e.g. 50–100 of 1,000 customers); enlarge batches only after
clean runs build confidence.
## Customer trust & communication
- You are responsible for ensuring customer orgs **aren't adversely affected**.
- Avoid changes that can break customer integrations (new **validation rules**, **formula fields**,
removed components). If unavoidable, **test thoroughly and communicate well in advance**.
- **Enhancing an existing feature:** use a **post-install script** to auto-assign new components via
**permission sets** — by default, new/changed components are assigned **only to admins**.
- **Brand-new features:** do **not** auto-assign. Coordinate with org admins on access and rollout timing.
---
## Eligibility reminders
- **2GP managed:** must have **passed AppExchange security review**; enable via a **Partner Community
support case**. Manageability rules for normal upgrades also apply to pushes.
- **Unlocked:** enabled by default.
- Target version must be **active, non-beta, released, non-deprecated**, and **strictly higher** than
each target org's installed version.
- **Subscriber restrictions:** if a subscriber has restricted push upgrades
(`HasRestrictionEnabled = true` / `CustomUpgradeType = 'BlockedBySubscriber'`), exclude them — the
request errors on restricted orgs.
## A sane rollout template
1. Push to internal test orgs → verify by logging in.
2. Push to customer **sandboxes** → soak ≥ 1 week.
3. Production **pilot** batch (50–100), off-peak, one time zone → monitor `PackagePushJob`/`PackagePushError`.
4. Grow production batches by time zone, off-peak, avoiding risky windows, only after clean runs.
5. Ship a post-install script + permission set if the version adds features users need immediately.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |