capgo-release-workflows
Designs repository-owned release pipelines for Capacitor apps that combine Capgo live updates, native builds (Capgo Build or the team's own CI runners), and App Store / Play publishing, with an automatic OTA-vs-native gate (bundle releaseType, build needed), staged channels, and rollback. Use when the user wants one release system covering OTA, builds, and store publishing, is replacing a hosted release service with CI they own, or asks how CI should decide between a live update and a store build. Do not use for single-step tasks (capgo-release-management, capgo-native-builds, capgo-live-updates), non-Capacitor apps, or Ionic Enterprise plugin migration (ionic-enterprise-sdk-migration).
- Installs
- 710
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cap-go/capgo-skills --skill capgo-release-workflows- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads capgo-release-workflows automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Capgo Release Workflows
Set up an end-to-end release system: Capgo OTA for web changes, native builds for binary changes, store publishing, and a CI gate that picks the right path.
When to Use
TRIGGER when:
- The user wants a single release pipeline covering live updates, native builds, and store publishing.
- The user is moving off a hosted release service (Appflow-style) to CI they own.
- The user asks "how does CI know if this needs a store release?"
Do not use when:
- The user needs one operation (upload or promote a bundle, request one build). Use
capgo-release-managementorcapgo-native-builds. - The user is wiring the updater plugin. Use
capgo-live-updates. - The user is migrating off Ionic Appflow specifically. Start with
ionic-appflow-migration, then return here for the pipeline. - The app is not Capacitor.
Building Blocks
| Area | Skill | Key command |
|---|---|---|
| OTA updates | capgo-live-updates, capgo-release-management | bundle upload, channel promote |
| Native builds on Capgo | capgo-native-builds | build request |
| Native builds on own runners | capacitor-ci-cd | Xcode / Gradle / Fastlane |
| Store listing and review | capacitor-app-store, capacitor-apple-review-preflight | n/a |
Procedure
1. Inventory (inspect, then report)
Find out:
- Which CI system runs (
.github/workflows,.gitlab-ci.yml,bitbucket-pipelines.yml,azure-pipelines.yml). - Whether
@capgo/capacitor-updateris installed with the major that matches@capacitor/core, and whethernotifyAppReady()is called. - The existing Capgo channels (
npx @capgo/cli@latest channel list <appId>) and the default channel. - Where native signing lives (Capgo credentials, CI secrets, Fastlane match).
- Whether store uploads are required, or only internal distribution.
Report the gaps to the user and ask before you choose Capgo Build or their own runners for native builds.
2. Define channels and versioning
- Typical channels:
development(self-assign),staging,production(default). - Use semver bundle versions. In CI, use
--bundle <ver>or--auto-bump patch, plus--version-exists-ok. - Set production to the metadata strategy once, so every upload records its native baseline:
npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata
3. Add the OTA-vs-native gate
# After npm ci && npm run build
if git diff --name-only "$BASE" HEAD | grep -qE '^(ios/|android/|capacitor\.config\.)'; then
TYPE=native
else
TYPE=$(npx @capgo/cli@latest bundle releaseType com.example.app --channel production | tr -d '[:space:]')
fi
releaseType prints OTA or native from native package metadata. It cannot see raw native edits, which is why the git-path check is there. build needed is the exit-code version: exit 1 means native is required, exit 0 means OTA is fine, exit 2 means the command failed.
4. Wire both branches
- OTA:
bundle upload --channel staging --fail-on-incompatible --auto-min-update-version, then a manual or approvedchannel promote staging production, optionally with--rollout 10. - Native: run
build request --platform ios|android(Capgo Build) or the native jobs, then upload the matching bundle with--auto-min-update-versionso the channel baseline advances. Do not pass--fail-on-incompatibleon that baseline upload, because the native packages are supposed to differ.
Full GitHub Actions and GitLab templates: https://capgo.app/docs/builder/ci-ota-or-native/
5. Rollback plan (write it down before the first release)
- OTA:
channel set production --bundle <previous>or--rollout-rollback. Auto-pause with--auto-pause-enabled --auto-pause-action rollback. - Native: there is no rollback in the stores. Ship a fixed build, and keep OTA able to patch the web layer.
6. Secrets
CAPGO_TOKEN(upload-capable, least privilege) andCAPGO_PRIVATE_KEYif bundles are encrypted.- Native signing: export from Capgo with
build credentials manage→.env, thengh secret set -f. Or keep the existing CI secret store. - Never commit
.capgo,.capgo_key_v2,.capgo-credentials.json, or.env.capgo.*.
Verification
Run once, end to end:
- A web-only commit takes the OTA branch. A device on staging gets the bundle (
npx @capgo/cli@latest app debug <appId>). - A commit that adds or upgrades a native plugin takes the native branch. The build succeeds and lands in TestFlight or the Play internal track.
- After the native release,
bundle releaseType --channel productionreturnsOTAagain for web-only changes. - A practice rollback (
channel set --bundle <previous>) reaches a test device.
Error Handling
- CI uploads fail with
No Capgo API key found:CAPGO_TOKENis not exported to the step'senv. Bundle NOT compatible with production channelin the OTA branch: the gate was skipped orreleaseTyperan against a different channel.- Signing failures: fix credentials first (
capgo-native-builds,build prescan) before you touch pipeline logic. - Store failures: split the iOS and Android jobs so one platform does not block diagnosis of the other.
Resources
- OTA or native in CI: https://capgo.app/docs/builder/ci-ota-or-native/
- CI/CD integration: https://capgo.app/docs/getting-started/cicd-integration/
- Capgo Build GitHub Actions: https://capgo.app/docs/builder/github-actions/
- Native + OTA channel workflow: https://capgo.app/docs/live-updates/native-ota-channel-workflow/
FAQ
What does the capgo-release-workflows skill do?
Designs repository-owned release pipelines for Capacitor apps that combine Capgo live updates, native builds (Capgo Build or the team's own CI runners), and App Store / Play publishing, with an automatic OTA-vs-native gate (bundle releaseType, build needed), staged channels, and rollback. Use when the user wants one release system covering OTA, builds, and store publishing, is replacing a hosted release service with CI they own, or asks how CI should decide between a live update and a store build. Do not use for single-step tasks (capgo-release-management, capgo-native-builds, capgo-live-updates), non-Capacitor apps, or Ionic Enterprise plugin migration (ionic-enterprise-sdk-migration).
How do I install capgo-release-workflows?
Run npx skills add https://github.com/cap-go/capgo-skills --skill capgo-release-workflows in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/capgo-release-workflows/ (personal) or .claude/skills/capgo-release-workflows/ (project).
Which AI agents can use capgo-release-workflows?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is capgo-release-workflows safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains capgo-release-workflows?
It is published by cap-go in cap-go/capgo-skills. It has 710 recorded installs.
More from cap-go/capgo-skills
capacitor-best-practices
cap-go/capgo-skills
Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).
ionic-design
cap-go/capgo-skills
Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).
capacitor-plugins
cap-go/capgo-skills
Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).
debugging-capacitor
cap-go/capgo-skills
Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).
capacitor-testing
cap-go/capgo-skills
Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor
safe-area-handling
cap-go/capgo-skills
Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.