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