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/objects.md
View on GitHub# Push upgrade — object reference
All live on the **Dev Hub / License Management Org**, not subscriber orgs.
**Query with the standard data API — NOT `--use-tooling-api`.** `PackageSubscriber`,
`PackagePushRequest`, `PackagePushJob`, and `PackagePushError` return "sObject type not supported"
under the Tooling API; query them with plain `sf data query --target-org <devhub> --query "..."`.
`MetadataPackage` and `MetadataPackageVersion` work under either API — use the standard one for
consistency. (Field lists below were verified via `sf sobject describe`, which works on both APIs and
is not a guarantee the object is Tooling-queryable — the query itself is.)
---
## PackageSubscriber — who has the package installed
The discovery object. One row per org/package install.
| Field | Type | Notes |
|-------|------|-------|
| `Id` | id | |
| `MetadataPackageId` | reference | The **033** package ID. Filter on this to scope to your package. |
| `MetadataPackageVersionId` | reference | The **04t** version the subscriber currently has. Compare to your target to find orgs that are behind. |
| `InstalledStatus` | picklist | `i` = installed, `u` = not installed / uninstalled. Filter `= 'i'`. |
| `OrgKey` | string | **The org ID that goes in the schedule CSV / `--org-list`.** |
| `OrgName` | string | Subscriber org name. |
| `OrgType` | picklist | `Production`, `Sandbox`. Pilot in sandboxes first. |
| `OrgStatus` | picklist | `Active`, `Demo`, `Free`, `Inactive`, `Trial`. Usually skip `Inactive`. |
| `InstanceName` | string | Instance (e.g. `NA123`) — useful proxy for time-zone batching. |
| `ParentOrg` | string | Parent org key (sandboxes trace to a parent). |
| `IsCustomUpgradeAllowed` | boolean | Whether custom upgrade handling is allowed. |
| `CustomUpgradeType` | picklist | `None`, `BlockedBySubscriber`. |
| `HasRestrictionEnabled` | boolean | `true` = subscriber has restricted push upgrades — **exclude these**; pushing to them errors. |
| `SystemModstamp` | datetime | |
---
## MetadataPackageVersion — resolve/validate the target version
| Field | Type | Notes |
|-------|------|-------|
| `Id` | id | The **04t** version ID. |
| `MetadataPackageId` | reference | The **033** package. |
| `Name` | string | Version name. |
| `MajorVersion` / `MinorVersion` / `PatchVersion` / `BuildNumber` | int | Compare against subscriber versions to confirm "strictly higher". |
| `ReleaseState` | picklist | `Beta`, `Released`. Push target must be `Released`. |
| `IsDeprecated` | boolean | Must be `false`. |
| `SystemModstamp` | datetime | |
---
## PackagePushRequest — one scheduled push (the `0DV`)
| Field | Type | Notes |
|-------|------|-------|
| `Id` | id | The **0DV** request ID. |
| `PackageVersionId` | reference | Target 04t version. |
| `ScheduledStartTime` | datetime | The UTC start you requested (null = ASAP). |
| `Status` | picklist | `Created`, `Pending`, `InProgress`, `Succeeded`, `Failed`, `Canceled`. |
| `StartTime` / `EndTime` | datetime | Actual execution window. |
| `DurationSeconds` | int | |
| `IsMigration` | boolean | `true` for 1GP→2GP push migrations. |
| `SystemModstamp` | datetime | |
Note: CLI `--status` filter shows `Cancelled`/`In Progress` (spacing); the object picklist uses
`Canceled`/`InProgress`.
---
## PackagePushJob — one per org within a request
| Field | Type | Notes |
|-------|------|-------|
| `Id` | id | |
| `PackagePushRequestId` | reference | Parent **0DV** request. |
| `SubscriberOrganizationKey` | string | The org this job targets (matches `PackageSubscriber.OrgKey`). |
| `Status` | picklist | `Created`, `Pending`, `InProgress`, `Succeeded`, `Failed`, `Canceled`. |
| `StartTime` / `EndTime` | datetime | |
| `DurationSeconds` | int | |
| `IsMigration` | boolean | |
| `SystemModstamp` | datetime | |
---
## PackagePushError — failure detail, attached to a job
| Field | Type | Notes |
|-------|------|-------|
| `Id` | id | |
| `PackagePushJobId` | reference | Parent job. |
| `ErrorSeverity` | picklist | `Warning`, `Error`. |
| `ErrorType` | picklist | `DeployError`, `ApexTestFailure`, `LockingFailure`, `IneligibleUpgrade`, … |
| `ErrorTitle` | string | Short label. |
| `ErrorMessage` | string | Human-readable message. |
| `ErrorDetails` | string | Extended detail / stack. |
| `SystemModstamp` | datetime | |
---
## ID prefix cheat sheet
| Prefix | Object |
|--------|--------|
| `033` | MetadataPackage (the package) — used by `push-upgrade list`. |
| `04t` | MetadataPackageVersion (the version) — the push **target**, `push-upgrade schedule --package`. |
| `0DV` | PackagePushRequest — returned by `schedule`, consumed by `report`/`abort`. |
| `00D` | Subscriber org ID — the `OrgKey` values in the CSV. |
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 |