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 |
README.md
View on GitHub# dx-packaging-push-upgrade-configure
A Salesforce agent skill that plans, schedules, and monitors **package push upgrades** from a
Dev Hub — end-to-end.
Push upgrades change a package **in the customer's org without their action**, so the skill's
default posture is **generate → preview → confirm → run**: it never calls `schedule` or `abort`
until the user has seen the batch plan and org list and said go.
## What it does
- **Resolves** the package (`033`) and a valid target version (`04t`) against the Dev Hub.
- **Finds subscribers** via `PackageSubscriber`, then applies eligibility filters (installed only,
below target, production vs sandbox, org status, subscriber restrictions).
- **Batches a schedule** per best practices — pilot in sandboxes, stagger production, off-peak by
time zone, avoid risky windows — and generates the per-batch org CSVs.
- **Runs** the `sf package push-upgrade schedule` commands after explicit confirmation.
- **Monitors** results via CLI and `PackagePushRequest` / `PackagePushJob` / `PackagePushError`,
and verifies the upgrade actually landed.
Supports 2GP managed, unlocked, and 1GP→2GP push migrations (`--migrate-to-2gp`).
## Inputs
The skill reads these from the request; provide whichever you have:
- `033…` → package ID
- `04t…` → target package version ID
- `0DV…` → existing push request ID (jumps straight to monitoring)
- a Dev Hub alias/username → the package-owning org (defaults to the configured `target-dev-hub`)
### Prerequisites
- Salesforce CLI (`sf`) authenticated to the Dev Hub / package-owning org.
- 2GP managed packages must have passed AppExchange security review and have push upgrades enabled
via a Partner Support case. Unlocked packages have them enabled by default.
- The *Create and Update Second-Generation Packages* user permission on the Dev Hub.
## Layout
| File | Purpose |
| --- | --- |
| `SKILL.md` | The skill definition and the phase-by-phase workflow. |
| `references/cli-reference.md` | Verified `sf package push-upgrade` subcommands and flags. |
| `references/objects.md` | Field reference for the push-upgrade objects. |
| `references/soql-recipes.md` | Ready-to-run subscriber and monitoring queries. |
| `references/best-practices.md` | Timing, testing, staggering, and communication guidance. |
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 |