Skip to content

forcedotcom/sf-skills / plugins/builder/dx-packaging/skills/dx-packaging-push-upgrade-configure

dx-packaging-push-upgrade-configure

Verified

Use 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.

FileKindSize
README.mdmarkdown2.3 KB
SKILL.mdskill md21.4 KB
references/best-practices.mdmarkdown3.2 KB
references/cli-reference.mdmarkdown7.5 KB
references/objects.mdmarkdown4.6 KB
references/soql-recipes.mdmarkdown4.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.
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall