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/soql-recipes.md

View on GitHub
# SOQL recipes — subscribers & monitoring

Run all with `sf data query --target-org <devhub> --query "..."` (the **standard** data API — do **not**
add `--use-tooling-api`; the push objects return "sObject type not supported" under Tooling).
Add `--result-format csv` to pipe straight toward a CSV (strip the header before feeding `--org-file`).

Placeholders: `<033>` = package ID, `<04t>` = target version ID, `<0DV>` = push request ID.

---

## Discover subscribers

### All currently-installed subscribers for a package
```sql
SELECT OrgKey, OrgName, OrgType, OrgStatus, InstanceName,
       MetadataPackageVersionId, InstalledStatus, HasRestrictionEnabled, CustomUpgradeType
FROM PackageSubscriber
WHERE MetadataPackageId = '<033>' AND InstalledStatus = 'i'
```

### Eligible production orgs, excluding restricted and already-on-target
```sql
SELECT OrgKey, OrgName, OrgStatus, InstanceName, MetadataPackageVersionId
FROM PackageSubscriber
WHERE MetadataPackageId = '<033>'
  AND InstalledStatus = 'i'
  AND OrgType = 'Production'
  AND OrgStatus != 'Inactive'
  AND HasRestrictionEnabled = false
  AND CustomUpgradeType != 'BlockedBySubscriber'
  AND MetadataPackageVersionId != '<04t>'
```
> `OrgType` (Production/Sandbox) and `OrgStatus` (Active/Demo/Free/Inactive/Trial) are **independent**
> — a Production org can be `Trial`, `Demo`, or `Free`, not just `Active`. Don't whitelist
> `OrgStatus = 'Active'` or you'll silently drop paying-but-non-`Active` production subscribers. Exclude
> only what you mean to (typically `Inactive`), and select `OrgStatus` so you can eyeball the mix.

### Sandboxes only (pilot batch)
```sql
SELECT OrgKey, OrgName, InstanceName, MetadataPackageVersionId
FROM PackageSubscriber
WHERE MetadataPackageId = '<033>' AND InstalledStatus = 'i' AND OrgType = 'Sandbox'
  AND HasRestrictionEnabled = false
  AND CustomUpgradeType != 'BlockedBySubscriber'
```

### Restricted / blocked orgs (report, then exclude from pushes)
```sql
SELECT OrgKey, OrgName, HasRestrictionEnabled, CustomUpgradeType
FROM PackageSubscriber
WHERE MetadataPackageId = '<033>' AND InstalledStatus = 'i'
  AND (HasRestrictionEnabled = true OR CustomUpgradeType = 'BlockedBySubscriber')
```

### Orgs on a specific old version (target a known-bad build)
```sql
SELECT OrgKey, OrgName, OrgType, InstanceName
FROM PackageSubscriber
WHERE MetadataPackageId = '<033>' AND InstalledStatus = 'i'
  AND MetadataPackageVersionId = '<04t-old-version>'
```

### Count by org type (population sanity check)
```sql
SELECT OrgType, COUNT(Id) total
FROM PackageSubscriber
WHERE MetadataPackageId = '<033>' AND InstalledStatus = 'i'
GROUP BY OrgType
```

> Note: `PackageSubscriber` has **no version-comparison operator** — you can only filter version by
> exact `MetadataPackageVersionId`. To push only to orgs *strictly below* the target, resolve each
> distinct installed version's numbers via `MetadataPackageVersion` and exclude any at/above the
> target before building the CSV.

---

## Resolve / validate versions

### Released versions of a package, newest first
```sql
SELECT Id, Name, MajorVersion, MinorVersion, PatchVersion, BuildNumber, ReleaseState, IsDeprecated
FROM MetadataPackageVersion
WHERE MetadataPackageId = '<033>' AND ReleaseState = 'Released'
ORDER BY MajorVersion DESC, MinorVersion DESC, PatchVersion DESC, BuildNumber DESC
```

### Validate a single target version
```sql
SELECT Id, MetadataPackageId, Name, MajorVersion, MinorVersion, PatchVersion, BuildNumber,
       ReleaseState, IsDeprecated
FROM MetadataPackageVersion
WHERE Id = '<04t>'
```
Target is valid only if `ReleaseState = 'Released'` and `IsDeprecated = false`.

---

## Monitor push requests

### Recent requests for a package
```sql
SELECT Id, PackageVersionId, Status, ScheduledStartTime, StartTime, EndTime, DurationSeconds, IsMigration
FROM PackagePushRequest
WHERE PackageVersionId IN (
  SELECT Id FROM MetadataPackageVersion WHERE MetadataPackageId = '<033>'
)
ORDER BY ScheduledStartTime DESC
```

### Jobs (per-org) for one request
```sql
SELECT Id, SubscriberOrganizationKey, Status, StartTime, EndTime, DurationSeconds
FROM PackagePushJob
WHERE PackagePushRequestId = '<0DV>'
ORDER BY Status
```

### Job status rollup for one request
```sql
SELECT Status, COUNT(Id) total
FROM PackagePushJob
WHERE PackagePushRequestId = '<0DV>'
GROUP BY Status
```

### Errors for a request (join through jobs)
```sql
SELECT PackagePushJobId, ErrorSeverity, ErrorType, ErrorTitle, ErrorMessage, ErrorDetails
FROM PackagePushError
WHERE PackagePushJobId IN (
  SELECT Id FROM PackagePushJob WHERE PackagePushRequestId = '<0DV>'
)
```

### Errors grouped by type (decide what to re-push)
```sql
SELECT ErrorType, ErrorSeverity, COUNT(Id) total
FROM PackagePushError
WHERE PackagePushJobId IN (
  SELECT Id FROM PackagePushJob WHERE PackagePushRequestId = '<0DV>'
)
GROUP BY ErrorType, ErrorSeverity
```
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