microsoft/power-platform-skills / plugins/mobile-apps/skills/deploy
deploy
VerifiedUse to deploy, publish, or push an Expo/React Native Power Apps mobile app to a Power Platform tenant.
Plugin check: Run
node "${PLUGIN_ROOT}/scripts/check-version.js"- if it outputs a message, show it to the user before proceeding.
π Shared instructions: shared-instructions.md β read first.
Deploy
Builds the mobile app in the current directory and pushes it to the Power Platform environment recorded in power.config.json.
This skill checks the app-matched verified release and actual selected bases before building and pushing. Read release lifecycle. Native compatibility is a separate gate from artifact format, environment confirmation, offline coverage, and TypeScript.
Out of scope (deliberately)
expo run:ios/expo run:androidβ local native compile is the user's choice; run your platform-specific native command directly when ready.- OTA updates and store distribution β out of scope for v0.
- Starting Metro for local dev β created apps use
npm run dev; template Metro config writes.powernativelogs for/debug-app.
Workflow
- Check memory bank β 1.2 Verified release + selected bases β 1.5 App ID preflight β 2. Build β 2.4 Native package β 2.5 Offline profile coverage gate β 3. Deploy β 4. Update memory bank
Step 1 β Check memory bank
Read memory-bank.md from the project root if present. Capture:
- Project name
- Environment (id + display name)
- Current version
If absent, continue β the project may have been created without the plugin. Re-derive env from power.config.json if needed.
Step 1.2 β Verified release and actual intended bases
Reject any --diagnostic-artifacts selection or local-diagnostic-only context
before building or pushing. Local test archives and APK metadata never authorize
tenant/store deployment, even when their hashes and counters match. Do not
silently replace the selection with a published/default release.
Resolve the app's installed/locked template, host, Expo, React Native, and native inventory; never use the newest bundled template as its runtime allowlist.
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/resolve-mobile-release.js" --project-root '<working_dir>'
Then obtain the actual intended base version, native runtime version and fingerprint for each target from the selected deployment target's verifiable metadata. Do not silently substitute the policy's expected values, assume βlatestβ, or claim a player/base is available because its package exists on npm. Missing selection is a blocker. If the target cannot expose these values, STOP; a version label alone does not prove matching native runtime content.
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/resolve-mobile-release.js" --project-root '<working_dir>' --platform android --base-version "<actual-intended-android-base-version>" --base-fingerprint "<actual-intended-android-base-fingerprint>" --base-runtime-version "<actual-intended-android-runtime-version>" || exit $?
node "${PLUGIN_ROOT}/scripts/resolve-mobile-release.js" --project-root '<working_dir>' --platform ios --base-version "<actual-intended-ios-base-version>" --base-fingerprint "<actual-intended-ios-base-fingerprint>" --base-runtime-version "<actual-intended-ios-runtime-version>" || exit $?
Every resolver invocation must succeed. Unknown/missing package contracts or base metadata
STOP before build/push. npm publication does not attest regional base availability;
that selection and publication check belongs to Wrap, not a skills catalogue.
Each deployment check requires --platform, --base-version, and
--base-fingerprint together, plus --base-runtime-version. The native runtime
and fingerprint must exactly match the published host contract; a missing or mismatched fingerprint blocks.
--requirements-only is planning-only and cannot authorize deployment.
There is no deploy without compatibility override. A successful web preview,
Metro run, native import, or Hermes magic check is not evidence of native
compatibility. A newer plugin/template is not an app upgrade.
Keep only the sanitized resolved tuple and selected base versions/fingerprints in the deployment summary; never dump raw app/auth/config files. Re-run these checks before each push and after any manifest, lockfile, host, native inventory, or base selection change, including the first-deploy second pass.
Package inclusion, OS declarations, runtime grants, and actual use remain distinct. Disabling controls does not remove unused default Android permissions. Different declarations require another verified base; optional per-customer permission wrapping is deferred. Do not edit plugins/permissions or run a local native build to bypass a mismatch.
Step 1.5 β App ID preflight (first-deploy gate)
Read power.config.json before building anything:
node -e "const c=require('./power.config.json');console.log(c.appId||'MISSING')"
-
Prints a GUID β normal path. Continue to Step 2.
-
Prints
MISSING(null, absent, or empty) β this is a first deploy. Say so plainly before doing any work:"β οΈ First deploy detected β
power.config.jsonhas noappIdyet. The app ID is minted by the first push, but it is compiled into the native bundle at build time. So two full build+push cycles are required. I'll run both; the second is not optional."Then run Steps 2 β 2.4 β 2.5 β 3 twice. In cycle 2,
npm run buildand the Step 2.4 native packaging commands must all re-run β the Hermes bundles from cycle 1 have an empty app ID compiled in. Step 2.5 (offline profile gate) may be skipped on cycle 2 only if no schema or profile file changed between the two cycles; if in doubt, re-run it β it is a local, no-network check.
Why two cycles are unavoidable. power-apps push mints the app ID and writes it back to power.config.json, but it refuses to run at all without an existing build β it fails immediately if the configured buildPath (./dist) is absent. So the ID cannot be minted before the first build, and the first build cannot contain the ID.
Why this is so easy to miss. The runtime guard is:
Platform.OS !== 'web' && !isDevPlayer && !hasConfiguredValue(powerConfig.appId)
Web is exempt, and so is Dev Player. The Code App, npm run dev, and the browser preview all look perfectly healthy. The failure appears only in the wrapped native app, as a full-screen red "App ID is missing β Push the mobile app to the Power Platform environment, rebuild it, and try again." That is after a base-package wrap, a signed build, and a device install β the most expensive possible place to discover a one-line config gap.
Step 2 β Build
Telemetry checkpoint: build_power_apps_bundle
Print before starting:
"β Building production web bundle via
npm run build(=expo export --platform web). ~30β90 seconds."
First regenerate connectorSchemas.ts so app/_layout.tsx's schemaMap import reflects every connector currently in .power/schemas/. The npm prestart/preandroid/preios hooks cover dev runs, but npm run build does not β if a connector was added since the last npm run dev, the bundled JS would ship a stale schema map. Always regenerate before build:
npm run generate-schemas
npm run build
If package.json has no build script, fall back to:
npx --no-install expo export --platform web
(Use the resolved app's scripts, not assumptions about the newest template.
Both forms produce dist/ web output, not a new native binary.)
Known issue β expo export --platform web never exits. The export finishes its work (writes dist/, prints Exported: dist and the asset count) and then hangs indefinitely. Reproduced deterministically across separate runs; observed still alive 2h34m after completing. dist/ is complete and correct when this happens. Suspected cause: the Metro config returned by createPowerAppsMetroConfig (metro.config.js) installs a dev-server middleware internally, which appears to hold an open handle β a web export should not need a dev server. Note the template itself only calls createPowerAppsMetroConfig; the middleware is applied inside @microsoft/power-apps-native-host, not in app code. Not yet root-caused.
Do not wait on the process. Run it detached and poll for the artifact. Per shared-instructions, scratch files stay project-local in .tmp/ β a fixed /tmp/ path would collide across concurrent projects, and a stale log there could satisfy the grep below and falsely report success:
mkdir -p .tmp
rm -f .tmp/expo-web-export.log
npx --no-install expo export --platform web > .tmp/expo-web-export.log 2>&1 &
EXPORT_PID=$!
for _ in $(seq 1 90); do
grep -q "Exported: dist" .tmp/expo-web-export.log 2>/dev/null && break
sleep 2
done
if ! grep -q "Exported: dist" .tmp/expo-web-export.log 2>/dev/null; then
echo "web export did not complete in 180s"; tail -30 .tmp/expo-web-export.log; exit 1
fi
test -f dist/index.html || { echo "dist/index.html missing"; exit 1; }
kill "$EXPORT_PID" 2>/dev/null || true
echo "β web export complete (process terminated manually β known hang)"
Treat a completed dist/ as success even though the process had to be killed. The Step 2.4 native packaging commands are not affected β both exit 0 cleanly and stage into dist/ via a temp dir, so they do not clear the web build.
If the build fails:
TS6133(unused import) β remove the import and retry once.- Other TypeScript errors β report file + line and STOP. Don't deploy a broken build.
- Metro bundler errors β surface the full stack and STOP.
Verify dist/ exists with index.html before continuing.
Step 2.4 β Native package (Hermes bundle + customer assets)
Print before starting:
"β Compiling the native Hermes bundle and hash-addressed asset package for iOS and Android. No JavaScript is compiled inside the wrap pipeline β it only consumes these prebuilt files. ~1β3 minutes."
Node version gate (required). Follow version-check.md and any higher engine requirements of the resolved release. Check the common Node 22+ floor first:
node -e 'const major=Number(process.versions.node.split(".")[0]); if (major < 22) { console.error("Node 22+ required; also check resolved release engines"); process.exit(1); }'
If this or a release-specific engine check fails, STOP and ask the user to switch to a supported Node version. Do not fetch newer native dependencies.
The web build above produces dist/index.html (the hosted Code App). Native wrapped apps additionally need a precompiled Hermes bundle and the customer's images/fonts as hash-addressed asset files, so the wrap pipeline never compiles or downloads JavaScript. Produce both platforms:
npm run bundle:android
npm run bundle:ios
Each command produces that platform's native Hermes bundle and its customer asset package, writing next to dist/index.html:
- Android:
dist/index.android.bundle.hbc(Hermes bytecode) +dist/powerapps-customer-assets-android/(manifest.json+assets/<fileHash>.<type>) - iOS:
dist/main.jsbundle.hbc(Hermes bytecode) +dist/powerapps-customer-assets-ios/(manifest.json+assets/<fileHash>.<type>)
Both platforms are required β the verification below fails if either bundle or either manifest is missing.
These sit alongside index.html under the same container SAS, so the wrap pipeline fetches them as siblings β no RP or connector change is required.
Verify before continuing β STOP on any failure (never push a web-only build for a native-wrapped app):
This checks packaging only. Hermes magic bytes identify the file format, not bytecode/engine ABI, Expo/RN, native module, player, or selected-base compatibility; Step 1.2 must also pass for both platforms.
# Hermes magic bytes on both bundles (expect c61fbc03)
for f in dist/index.android.bundle.hbc dist/main.jsbundle.hbc; do
test -f "$f" || { echo "MISSING $f"; exit 1; }
node -e 'const fs=require("fs"),b=Buffer.alloc(4),fd=fs.openSync(process.argv[1],"r");fs.readSync(fd,b,0,4,0);fs.closeSync(fd);process.exit(b.toString("hex")==="c61fbc03"?0:1)' "$f" || { echo "$f is not Hermes bytecode"; exit 1; }
done
# both asset manifests present
test -f dist/powerapps-customer-assets-android/manifest.json || { echo "MISSING android manifest"; exit 1; }
test -f dist/powerapps-customer-assets-ios/manifest.json || { echo "MISSING ios manifest"; exit 1; }
echo "β native package + asset manifests present"
If a native packaging step fails, surface the error and STOP. If the app renders bundled images/fonts, also confirm each manifest.json assets array is non-empty (an empty array means the app doesn't require() any static asset yet).
Step 2.5 β Offline profile coverage gate
Telemetry checkpoint: validate_offline_profile_coverage
This is the final chance to catch schema that never made it into the Mobile Offline Profile before it ships β a table added to the data model but not the profile never syncs to devices, and a new column arrives blank offline. Validate that every schema change is covered before pushing.
For this offline gate, first resolve the approved app's absolute working_dir
using app-working-directory.md
before running the check below or any helper. Bind every offline check, file
read, and helper call to that same root.
Run the local, no-network delta check (.datamodel-manifest.json vs offline-profile.json):
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/offline-profile-delta.js" --project-root '<working_dir>'
Branch on the JSON status (full contract in offline-profile-reconciliation.md):
status | Action |
|---|---|
no-manifest | Connectors-only app β no Dataverse schema. Continue to Step 3 silently. |
no-profile | No offline profile in this project. Print one line: β· No offline profile β skipping offline coverage check. Run /setup-offline-profile if you want offline support. Continue to Step 3. |
in-sync | Print β Offline profile covers all schema changes. Continue to Step 3. |
error | offline-profile.json is unreadable β the script prints status: error and exits non-zero. Offline coverage can't be validated against a corrupt file, so STOP before pushing: surface the error string and have the user fix offline-profile.json and re-run, or type the deploy without offline override (below) to push anyway. |
delta | STOP before pushing. See below. |
On delta β print the uncovered schema, then gate with AskUserQuestion:
β The offline profile is missing schema changes. If you deploy now, these won't be
available on disconnected devices:
Tables not in the profile : <missingTables[].logicalName>
Tables with new columns : <tablesWithNewColumns[].logicalName (newColumns)>
Options:
- Update the offline profile now (recommended) β use the reconciliation reference's Scoped helper handoffs with
orchestrator: deploy, absoluteworking_dir,phase: implementation, and the approved environment/profile/table scope. Read and execute${PLUGIN_ROOT}/skills/add-table-to-offline-profile/SKILL.mdwith--working-dir '<working_dir>' --table <t>for each approvedmissingTables[]entry, then${PLUGIN_ROOT}/skills/edit-offline-profile/SKILL.mdwith those arguments plus--columns add:<newColumns>for each approvedtablesWithNewColumns[]entry. Re-run the guarded delta check; when it reportsin-sync, continue to Step 3. - Deploy anyway β requires an explicit override. Wait for the exact phrase
deploy without offline(case-insensitive); a barey/yesis not enough, mirroring the environment-mismatch gate in Step 3. Then continue to Step 3 and note the skipped reconciliation in the Step 4 build-history row.
Do not push until the gate is resolved (reconciled to in-sync, or explicitly overridden).
Step 3 β Deploy
Telemetry checkpoint: push_app_to_power_platform
Re-run Step 1.2 for the app and both actual intended base versions and fingerprints before this push. Neither the environment override nor the offline override can waive it.
Resolve and confirm the target environment FIRST. pa app push deploys to the environment configured in power.config.json. Resolve that ID to a Dataverse URL so the user catches drift before pushing.
Run:
ENV_ID=$(node -e "console.log(require('./power.config.json').environmentId)")
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$ENV_ID"
From resolve-environment.js capture the Environment URL (e.g. https://contoso.crm.dynamics.com/), Environment ID, and Tenant ID. Cross-check against memory-bank.md / power.config.json:
- Match β proceed to the confirmation prompt below.
- Mismatch β STOP. Surface both values side-by-side and ask the user to either (a) update
power.config.jsonby re-running init in the intended app root, or (b) explicitly typeoverrideto push to the environment already recorded inpower.config.json. Do not proceed on a barey. - Cannot resolve/authenticate β STOP with
az login --tenant <env-tenant>instructions, or ask the user to provide the environment URL directly.
Print before starting:
"β Pushing bundle to Power Platform via
pa app push. ~30β60 seconds."
Confirm with the user using the resolved env URL, not just the friendly name:
"Ready to deploy to (
<env-url>)? This will update the live app for every user in that environment. Typeyes deploy to <env-name>to confirm."
Wait for the exact phrase yes deploy to <env-name> (case-insensitive, env-name matching). A bare y / yes is not enough β too easy to fire on autopilot when the wrong env is active. Then:
Resolve the CLI first (see cli-binary.md): run as
$PA app push(npx --no-install pa β¦), never a barepa. Onpower-apps-only projects, translate topower-apps push.
$PA app push --non-interactive
Capture the app URL from the output if printed.
First-deploy loop-back. If Step 1.5 reported MISSING, re-read the config now:
node -e "const c=require('./power.config.json');console.log(c.appId||'STILL MISSING')"
- GUID β the app was registered. Go back to Step 2 and run Build β 2.4 β 2.5 β Deploy one more time. The artifacts now sitting in
dist/(and already uploaded to the blob) still have an empty app ID compiled in; without the second cycle the wrapped app fails on-device. Step 2.5 may be skipped on this second pass only if nothing under.datamodel-manifest.json/offline-profile.jsonchanged since cycle 1. STILL MISSINGβ push did not register the app. STOP and report. Do not proceed to wrap.
On the second pass this check is a no-op, and Step 4 runs as normal.
If deploy fails, report the error and STOP β do not retry silently. Common fixes:
| Error | Fix |
|---|---|
pa app push auth error, wrong user, or multiple accounts | Follow shared-instructions command-failure handling. az login / az account set does not switch the standalone Power Apps CLI account. |
| Environment mismatch | Re-run $PA app init -t MobileApp --display-name <name> --environment-id <id> --non-interactive in a fresh/app root for the intended target |
$PA is empty (PA_KIND=none β CLI not installed) | Ask the user to restore the resolved release's existing exact locked dependencies in the project root, then re-resolve $PA per cli-binary.md. Never fall back to a bare npx pa or npx power-apps, a newer host/native package or an unrelated global CLI. |
Step 4 β Update memory bank
If memory-bank.md exists, increment the version (v1.0.0 β v1.1.0) and update:
- Current version
- Last deployed timestamp
- App URL (if captured)
- Append a row to the Build history section:
| v1.1.0 | <timestamp> | deploy | success | - Record the sanitized verified release tuple and both actual selected base versions/fingerprints; record native device validation separately from packaging success.
Print the summary card:
β
Deploy β <project-name>
βββββββββββββββββββββββββββββββββββββββββββββ
Version : <new-version>
Environment : <env-name>
App URL : <url or "see make.powerapps.com">
Bundle path : dist/
Local dev: npm run dev (writes .powernative logs for /debug-app)
Re-deploy: /deploy
List conns: /list-connections
βββββββββββββββββββββββββββββββββββββββββββββ
Local dev (out of scope for this skill β for reference only)
When the user wants normal Expo iteration with portable monitoring, they can run:
npm run dev # Metro + QR + .powernative log
This launches Metro, prints a QR code, and writes sanitized output to .powernative/metro-logs/ so /debug-app can reattach after a host/session restart. They can:
- Scan the QR with the installed native dev client
- Reload from the native dev-client menu
Do not use React Native Web, browser automation, direct Metro/localhost HTTP probes, or screen-by-screen runtime checks.
If they want to compile a native binary locally, they run the platform-specific native command directly. Local native compile and manual device testing are user-owned and are not deployment gates for this skill.
Reference
shared/version-check.mdβ min versions (only Always-required tier matters here)shared/memory-bank.mdβ Build history schemashared/references/offline-profile-reconciliation.mdβ Step 2.5 offline coverage gate
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path β even casually (like "the xlsx in my downloads") β and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |