Migrates Ionic or Capacitor projects from Ionic Appflow to Capgo for live updates, cloud builds, and store deployment.
- GitHub stars
- 78
- Files
- 2
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- 2
What does the ionic-appflow-migration skill do?
ionic-appflow-migration migrates Ionic or Capacitor projects from Ionic Appflow to Capgo for live updates, cloud builds, and store deployment.
Summary generated from the skill's SKILL.md.
About the ionic-appflow-migration skill
Developers managing Ionic or Capacitor projects can use this skill to transition away from Ionic Appflow before its access ends in late 2027. It automates the replacement of Appflow features with Capgo alternatives, specifically targeting Live Updates, native cloud builds, and store deployment workflows. The process involves auditing the existing codebase for specific packages like @capacitor/live-updates or cordova-plugin-ionic and configuration files such as .io-config.json or capacitor.config.ts.
An agent should load this skill when it detects Appflow-related dependencies, scripts, or CI/CD workflows in a repository. The skill produces a migration plan and executes the technical replacement of SDKs, mapping Appflow update strategies and API calls to the @capgo/capacitor-updater library. It also assists in setting up Capgo Cloud Build or repo-owned CI pipelines to replace Appflow's native build and store publishing capabilities. This tool is strictly for Appflow migrations and should not be used for enterprise plugins or fresh Capgo installations.
What an agent can do with it
- 1Audit Appflow dependenciesIdentify all Appflow-related packages, scripts, and configuration files within a project to prepare for migration.
- 2Migrate Live Updates to CapgoReplace the Appflow Live Updates SDK with the Capgo capacitor updater and update the configuration files.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the ionic-appflow-migration skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the ionic-appflow-migration skill in Claude Code
~/.claude/skills/ionic-appflow-migration/SKILL.md
$ npx degit Cap-go/capgo-skills/skills/ionic-appflow-migration ~/.claude/skills/ionic-appflow-migrationInstall the ionic-appflow-migration skill in Claude Code (project)
.claude/skills/ionic-appflow-migration/SKILL.md
$ npx degit Cap-go/capgo-skills/skills/ionic-appflow-migration .claude/skills/ionic-appflow-migrationInstall the ionic-appflow-migration skill in Codex
~/.agents/skills/ionic-appflow-migration/SKILL.md
$ npx degit Cap-go/capgo-skills/skills/ionic-appflow-migration ~/.agents/skills/ionic-appflow-migrationInstall the ionic-appflow-migration skill in Gemini CLI
~/.gemini/skills/ionic-appflow-migration/SKILL.md
$ npx degit Cap-go/capgo-skills/skills/ionic-appflow-migration ~/.gemini/skills/ionic-appflow-migrationInstall the ionic-appflow-migration skill in Claude.ai
npx degit Cap-go/capgo-skills/skills/ionic-appflow-migration ionic-appflow-migration && zip -r ionic-appflow-migration.zip ionic-appflow-migration # claude.ai → Customize → Skills → + → Create skill → Upload a skill → ionic-appflow-migration.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablecap-go/capgo-skills/skills/ionic-appflow-migration is public and reachablegithub.com/cap-go/capgo-skills/tree/HEAD/skills/ionic-appflo ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/cap-go/capgo-skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/cap-go/capgo-skills/blob/HEAD/skills/ionic-appflo ↗Pass
- Pre-approved tools are scopedPre-approved: Bash(node -e *), Bash(find *)github.com/cap-go/capgo-skills/blob/HEAD/skills/ionic-appflo ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 147 linesgithub.com/cap-go/capgo-skills/blob/HEAD/skills/ionic-appflo ↗Pass
SKILL.md
View on GitHubIonic Appflow Migration
Replace each Appflow feature the project uses - Live Updates, native cloud builds, store deployment - and remove Appflow only after each replacement is verified.
Context: Ionic stopped selling Appflow in February 2025; existing customers keep access until December 31, 2027 with no new features. Plan the migration well before that date.
When to Use
TRIGGER when:
package.jsonhas@capacitor/live-updatesorcordova-plugin-ionic.capacitor.config.*hasplugins.LiveUpdates, orconfig.xml/Info.plist/strings.xmlhold Appflow deploy keys (APP_ID,CHANNEL_NAME,UPDATE_METHOD,IonAppId,IonChannelName).- CI calls
ionic deploy,appflow,ionic package build, or the Appflow dashboard triggers builds and store uploads.
Do not use for:
@ionic-enterprise/*plugins ->ionic-enterprise-sdk-migration.- Capawesome Cloud ->
capawesome-live-update-migration. - Greenfield Capgo setup ->
capgo-live-updates.
Live Project Snapshot
Detected Appflow-related packages and scripts:
!node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name==='@capacitor/live-updates'||name==='cordova-plugin-ionic'||name.includes('appflow')||name==='@ionic/cli'||name==='@capgo/capacitor-updater'||name==='@capacitor/core')out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(/appflow|ionic deploy|ionic package|live-updates/i.test(cmd))out.push('scripts.'+name+'='+cmd)}console.log(out.join('\n'))"
Possible Appflow config and workflow paths:
!find . -maxdepth 4 -not -path '*/node_modules/*' \( -name '.io-config.json' -o -name 'ionic.config.json' -o -name 'config.xml' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -path './.github/workflows/*' -o -name '.gitlab-ci.yml' -o -name 'appflow.config.json' \)
Procedure
Step 1: Inventory (report before editing)
rg -n "@capacitor/live-updates|cordova-plugin-ionic|LiveUpdates|IonAppId|IonChannelName|UPDATE_METHOD|CHANNEL_NAME|ionic deploy|appflow|dashboard.ionicframework.com|ionic.io/appflow" \
-g '!node_modules' .
Record per feature:
- Live Updates: SDK in use, Appflow app ID, channels and which binaries point at them, update method (
background,none, always-latest on resume, force update),maxVersions, any code callingsync(),download(),extract(),reload(). - Native builds: build stack, signing certificates/profiles and keystores stored in Appflow, environment variables, native config overrides.
- Store deploys: TestFlight / Play destinations and tracks.
Ask the user to export signing credentials from Appflow (or confirm they have originals) before deleting anything there.
Step 2: Live Updates -> Capgo
npm uninstall @capacitor/live-updates # or: npm uninstall cordova-plugin-ionic
npm install @capgo/capacitor-updater
npx cap sync
For cordova-plugin-ionic, also remove its <plugin>/<variable> entries from config.xml and any Ion* keys from native files.
Replace the config block:
// capacitor.config.ts
plugins: {
// remove LiveUpdates: { appId, channel, autoUpdateMethod, maxVersions }
CapacitorUpdater: {
autoUpdate: true,
autoDeletePrevious: true,
},
},
| Appflow | Capgo |
|---|---|
appId |
Capgo app created with npx @capgo/cli@latest init (uses appId from capacitor.config) |
channel |
Capgo channel (dashboard/CLI); set default channel server-side, or defaultChannel in config for per-build overrides |
autoUpdateMethod: 'background' |
autoUpdate: true (default behaviour: download in background, apply on next start) |
autoUpdateMethod: 'none' + manual sync() |
Keep autoUpdate: true unless the product needs custom timing; otherwise autoUpdate: false + manual API |
maxVersions |
autoDeletePrevious: true plus server-side bundle retention |
| Binary-version targeting | Channel per native major, or --min-update-version / metadata strategy (capgo-release-workflows) |
| Force update | Mark bundle/channel behaviour in Capgo and listen for majorAvailable or use directUpdate |
Add the one required hook once the app shell renders:
import { CapacitorUpdater } from '@capgo/capacitor-updater';
void CapacitorUpdater.notifyAppReady();
Without it Capgo treats the bundle as broken and rolls back.
API mapping (keep manual calls only if the product needs custom UI or timing):
Appflow (@capacitor/live-updates) |
Capgo |
|---|---|
LiveUpdates.sync() |
Not needed with autoUpdate: true; manual: CapacitorUpdater.getLatest() + download() |
LiveUpdates.reload() |
CapacitorUpdater.set({ id }) (applies and reloads) or reload() |
resume listener calling sync() |
Remove; auto-update checks on resume |
SplashScreen.hide() after sync |
Plain SplashScreen.hide() after app boot; optional appReady listener |
Upload the first bundle to a test channel:
npm run build
npx @capgo/cli@latest bundle upload --channel development
Step 3: Native cloud builds
Two replacements; ask which the user prefers:
- Capgo Cloud Build:
npx @capgo/cli@latest build credentials save --platform ios|android ..., thennpx @capgo/cli@latest build request <appId> --platform ios|android. Details incapgo-native-builds. - Repo-owned CI (GitHub Actions, GitLab, Fastlane):
capacitor-ci-cd.
Carry over environment variables, build-time config, and signing inputs exactly; change one thing at a time.
Step 4: Store publishing
Capgo Cloud Build can upload to TestFlight / Play when store credentials are saved; otherwise use CI upload steps (capacitor-ci-cd) or manual submission (capacitor-app-store). Keep bundle IDs, Play tracks, and credentials unchanged.
Step 5: Cut over and clean up
- Ship a native build containing
@capgo/capacitor-updaterto the stores. Devices on older binaries keep pulling from Appflow until they update - keep Appflow channels live until adoption is high enough. - Publish web updates to both systems during the overlap, or freeze Appflow at the last bundle shipped with the new binary.
- Remove Appflow packages,
plugins.LiveUpdates,.io-config.jsonreferences, Appflow CI jobs, and secrets once no supported binary depends on them.
Verification
rg -n "@capacitor/live-updates|cordova-plugin-ionic|LiveUpdates\\." -g '!node_modules' .returns nothing (after cleanup).- Fresh install of the new binary: logs show
notifyAppReadycalled; Capgo dashboard shows the device. - Upload a test bundle to a non-production channel; device downloads and applies it on next start.
- Upload a deliberately broken bundle (no
notifyAppReady) to the test channel; device rolls back. - New native build pipeline produces signed IPA/AAB with the same bundle ID and a higher build number.
Error Handling
| Problem | Fix |
|---|---|
| App rolls back every update | notifyAppReady() not reached (called too late, behind login, or code path throws); call it right after the shell renders |
Cannot find API key in local folder or global, please login first from the Capgo CLI |
npx @capgo/cli@latest login <apikey> locally, or CAPGO_TOKEN in CI |
| Updates never arrive | Device on a channel without the bundle, or bundle incompatible with native version; check channel and npx @capgo/cli@latest bundle compatibility |
| Old Appflow update overwrote Capgo bundle | Old SDK still installed in the binary; confirm @capacitor/live-updates / cordova-plugin-ionic removed and npx cap sync run before building |
| Build fails after removing Appflow | Appflow injected env vars or native config; recreate them in CI or Capgo Cloud Build environment |
Files in this skill
2ionic-appflow-migration skill questions
How do I install the ionic-appflow-migration skill in Claude Code?
Run npx degit Cap-go/capgo-skills/skills/ionic-appflow-migration ~/.claude/skills/ionic-appflow-migration. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the ionic-appflow-migration skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
When should I use this migration skill?
Use this when your project contains @capacitor/live-updates, cordova-plugin-ionic, or Appflow configuration blocks and you want to move to Capgo.
What should I do if my app rolls back every update after migration?
This usually means notifyAppReady() was not reached; ensure you call it immediately after the app shell renders.
Can I use this skill to migrate Ionic Enterprise plugins?
No, this skill is not for migrating Ionic Enterprise plugins like Identity Vault or Auth Connect; use ionic-enterprise-sdk-migration instead.