App Store phased release: percentages, pausing and release options
Phased release on the App Store rolls a version update out to users with automatic updates over 7 days: 1%, 2%, 5%, 10%, 20%, 50%, then 100% on day 7. You turn it on per version in App Store Connect, can pause it for up to 30 days in total, and can release to everyone at any time.
It only throttles automatic updates. Anyone can open the App Store and update by hand on day one, and new downloads get the new version straight away, so a phased release limits how many existing users a bad build reaches without hiding it from anyone. App Store Connect has no rollback: if day 2 shows a crash, you pause, ship a fixed build and let the fix replace it.
By Redjan Hysa, founder of MetaRun · Facts checked October 12, 2026
- length of a phased release, plus any days spent paused
- 7 days
- of automatic-update users get the update on day 1
- 1%
- total pause budget, across any number of pauses
- 30 days
- a first release can't be phased
- Updates only
- platforms Apple's phased release help page covers
- iOS, macOS, tvOS
Reference tables
| Day | Users with automatic updates who get the version |
|---|---|
| 1 | 1% |
| 2 | 2% |
| 3 | 5% |
| 4 | 10% |
| 5 | 20% |
| 6 | 50% |
| 7 | 100% |
From Apple's help page. Apple picks a random sample of users with automatic updates on eligible devices and doesn't tell them they're part of a phased release.
| Option (App Store Version Release) | What happens after approval | Works with phased release |
|---|---|---|
| Manually release this version | The version waits in Pending Developer Release until you click Release This Version. Apple emails a reminder after 30 days. | Yes |
| Automatically release this version | It goes live as soon as App Review approves it. | Yes |
| Automatically release this version after App Review, no earlier than [date] | If approval lands before the date, the version waits in Pending Developer Release and releases on the date you set. | Yes |
If the app is set up for pre-order and has never been released, App Store Connect dims this section and selects manual release.
| Version status | What you can do |
|---|---|
| Prepare for Submission, Waiting for Review, In Review, Waiting for Export Compliance | Turn phased release on or off. |
| Rejected, Metadata Rejected, Developer Rejected | Turn phased release on or off. |
| Pending Developer Release | Turn it on or off, then release the version. |
| Ready for Distribution, phased release running | Pause, or Release to All Users. |
| Ready for Distribution, phased release paused | Resume where it stopped, or Release to All Users. |
| Ready for Distribution, no phased release | Nothing to control: automatic updates already go to everyone. |
The statuses that allow turning it on are the ones Apple lists on its phased release help page.
How to set up and control a phased release in App Store Connect
You need the Account Holder, Admin or App Manager role. The example is version 2.4, an update to an app that's already live.
- 01
Turn phased release on
In Apps, select the app and click version 2.4 in the sidebar. Scroll to Phased Release for Automatic Updates, select "Release update over a 7-day period using phased release", then click Save.
- 02
Pick a release option
In the App Store Version Release section, choose manual, automatic, or automatic no earlier than a date and time, then Save. Do it before you submit so the approval does what you expect.
- 03
Release and watch
After approval the version shows Ready for Distribution with "Phased Release" next to the status (for a manual release, click Release This Version first). Admins and App Managers get a notification when the rollout completes.
- 04
Pause or resume
Click the Ready for Distribution version. In Phased Release for Automatic Updates, select Pause Phased Release, then Save. To resume, switch back to the Use Phased Release option and Save; the rollout continues from the day it stopped.
- 05
Release to all users early
On the same version page, click Release to All Users at the top right. Every device with automatic updates on gets the latest version it supports.
What phased release does and doesn't control
The percentages apply to one audience: existing users with automatic updates turned on. Apple's help page is explicit that apps and updates in phased release can be downloaded from the App Store by anyone at any time. So a user who taps Update on the product page, or someone installing the app for the first time, gets version 2.4 on day 1 whatever the percentage says.
Plan around that. If 2.4 needs a server migration or a new backend endpoint, the backend has to serve both 2.3 and 2.4 clients for the whole week and beyond, because some people turn automatic updates off and stay on old versions for months. Treat phased release as a way to limit how many people a crash reaches. For a private test, use TestFlight.
Phased release vs manual release
These are two separate settings that people often treat as one. The release option decides when the version goes live: right after approval, when you click Release This Version, or no earlier than a date you choose. Phased release decides how fast automatic updates spread once it's live.
They combine well. A common setup for a launch is manual release plus phased release: App Review approves 2.4 on Tuesday, it sits in Pending Developer Release, you release it alongside Thursday's announcement, and automatic updates then ramp over the following week. Apple's help page doesn't say when the release option stops being editable, so set both before you click Submit for Review.
Pausing, and how long a phased release takes
You can pause as often as you like, but the pauses share one 30-day budget. Pause for 10 days, resume, and 20 days remain for later pauses. A resumed release picks up on the day it stopped, so a rollout paused on day 3 continues at day 3's 5%, not back at 1%. That makes the total length 7 days plus whatever time it spent paused.
Removing the app from sale, which includes a lapsed Apple Developer Program membership, stops the phased release for good. When the app is reinstated, that version goes to all users at once regardless of the percentage it had reached. To get a controlled rollout back, Apple says to make the version unavailable for download and submit a new update with phased release on.
When a bad build is rolling out
Pause first. That stops new automatic updates; it doesn't uninstall the build from people who already have it, and manual updates keep working. Then fix the bug, bump the version (2.4.1, build 315) and submit it with phased release on. A critical bug fix is the textbook case for an expedited review: submit first, put the steps to reproduce the bug on the current version in the Notes field, then file the request.
There's no way to put 2.3 back on the store. The only lever after release is shipping something newer, which is why a remote feature flag or kill switch for risky new code is worth having before day 1. If the problem is fixed server side and 2.4 itself is fine, resume the rollout instead of shipping a new build.
Common problems and how to fix them
Can't turn on phased release for a version
Why: The version is past the statuses where Apple allows it: once a version is Processing for Distribution, Pending Apple Release or Ready for Distribution, the rollout speed is already decided.
Fix: For a live version, it's too late; turn it on for the next update while it's in Prepare for Submission or anywhere up to Pending Developer Release.
Phased release option missing from the version page
Why: Phased release is only offered for version updates, so a first version can't use it. Apple's help page also covers only iOS, macOS and tvOS, and changing it needs the Account Holder, Admin or App Manager role.
Fix: Check the version is an update on one of those platforms and that your user role allows release changes. For a first launch, use manual release to control timing instead.
Phased release paused too long, or no pause days left
Why: All pauses draw on the same 30-day total. Apple's help page doesn't describe what happens when the budget runs out.
Fix: Count paused days from the first pause, not the latest one, and have the fix approved or Release to All Users before the 30 days are used.
Users already have the update on day 1
Why: Phased release only throttles automatic updates. Manual updates from the App Store and new downloads aren't limited.
Fix: Nothing to fix. If the build is bad, pause to stop automatic updates and ship a corrected version.
Do it from Claude Code, Codex, Cursor or Xcode with MetaRun
Release settings live in two places in App Store Connect: the version's release option (manual, automatic after approval, or a scheduled date) and the phased release toggle. After launch the phased release has its own pause and resume controls. None of it is hard, but it's always needed at the moment you're watching crash numbers somewhere else.
MetaRun exposes each control as a preview and apply pair. Your agent can read the version's state, change the release option before approval, release a version that's waiting for you, and move a phased rollout through start, pause, resume, complete or cancel.
Before you start
- A version that's approved and waiting, or already live with phased release on.
- For release options: a version that hasn't been submitted yet.
- An API key with the Admin or App Manager role.
How the agent runs it
- 01
Read where the version stands
Your agent reads the version state first. Release options only change before submission; a manual release only applies to a version that's waiting for developer release.
- 02
Preview the transition
Every control previews the exact transition, for example phased release from active to paused, with a confirm token tied to the current state.
- 03
Apply on your approval
Your agent asks before running the apply. If the rollout moved in the meantime (someone paused it in App Store Connect), the token is stale and the apply refuses.
- 04
Check the history
Each change lands in MetaRun's change history, attributed to the agent, next to manual and MILO changes for the same app.
An example session
Set 2.4 to release automatically after approval with a phased rollout.
- apple_list_versionsVersion 2.4 is Ready for Sale, phased release active.
- apple_list_reviewsSeveral new reviews mention a crash on launch since 2.4.
- apple_preview_phased_releasePreview: pause, from Active to Paused.
- Your agent asks before running apple_apply_phased_release. You read the preview above and approve.
- apple_apply_phased_releasePaused. Automatic updates stop; people can still update by hand.
Illustrative: your apps, versions and numbers will differ. The tool names and their order are real.
The MetaRun tools involved
| Tool | What it does |
|---|---|
| apple_list_versionsread | Versions with their state, so the agent knows what's approved and what's live. |
| apple_preview_set_release_optionspreview + apply | Manual, automatic after approval, or scheduled with an earliest release date. |
| apple_preview_phased_releasepreview + apply | Start, pause, resume, complete or cancel a phased rollout. |
| apple_preview_manual_releasepreview + apply | Release an approved version that's waiting for you. Irreversible. |
| apple_preview_set_territory_releasepreview + apply | Change availability, release date or pre-order for individual territories. |
| apple_get_perf_metricsread | Apple's performance metrics for the app, to check before widening a rollout. |
| apple_list_reviewsread | Recent customer reviews, to catch complaints about the new version. |
Each preview has an apply twin that only runs with the confirm token from a fresh preview, and refuses if App Store Connect changed in between.
What Apple enforces along the way
A phased release runs for 7 days
Apple widens automatic updates over seven days: 1%, 2%, 5%, 10%, 20%, 50%, then everyone. New downloads and manual updates get the new version from day one.
Pausing has a 30-day budget
You can pause a phased release for up to 30 days in total. Completing it releases to all users at once.
Releasing is irreversible
A manual release can't be undone, which is why the preview says so and the tool is marked outward. Pulling a bad version means a new build, not a rollback.
Release options lock at submission
MetaRun changes a version's release option while the version is being prepared, ready for review or rejected, the states where App Store Connect accepts edits to it. Set it before you submit.
Set up your agent
Connect once, then ask in plain words. Pick your agent:
Claude Code Anthropic
Run claude mcp add --transport http --scope user metarun https://metarun.dev/api/mcp, then run /mcp in Claude Code and sign in to MetaRun in your browser.
01 · Add the server
Run it in any terminal. --scope user makes MetaRun available in every project; leave it out to limit it to the current one.
claude mcp add --transport http --scope user metarun https://metarun.dev/api/mcp02 · Sign in
In a Claude Code session, run /mcp, choose metarun and authenticate. MetaRun opens in your browser, where you pick read-only or read and change. From a plain shell, claude mcp login metarun does the same.
/mcp03 · Optional: add the skills too
The MetaRun plug-in bundles the same server with six mission skills (release handoff, worldwide pricing, localization, review inbox, ASO audit, store media).
claude plugin marketplace add metarun/metarun-skills
claude plugin install metarun-skills@metarunThen ask Claude Code
- Ask Claude Code: Set 2.4 to release automatically after approval with a phased rollout.
- Ask Claude Code: Crash rate on 2.4 just doubled. Pause the phased release now and show me the last 20 reviews.
- Ask Claude Code: Everything looks fine after three days. Complete the phased release for 2.4.
claude -p runs one request with no interactive session. The browser sign-in can't complete inside -p, so sign in once interactively first, or configure the server with a personal access token in CI. Tools missing from --allowedTools are refused in -p mode.
Read-only check, safe to schedule
claude -p "Report the state of the latest version of com.example.app and its phased release, including the current rollout day. Read only." \
--allowedTools "mcp__metarun__apple_list_versions,mcp__metarun__apple_preview_set_release_options,mcp__metarun__apple_preview_phased_release,mcp__metarun__apple_preview_manual_release,mcp__metarun__apple_preview_set_territory_release,mcp__metarun__apple_get_perf_metrics,mcp__metarun__apple_list_reviews"Only reads and previews are on that list, so nothing can reach App Store Connect unattended. Run applies in an interactive session where Claude Code can ask you.
Codex OpenAI
Run codex mcp add metarun --url https://metarun.dev/api/mcp; Codex detects MetaRun's sign-in and opens it in your browser.
01 · Add the server
Codex sees that MetaRun offers sign-in and starts it straight away, in your browser. Pick read-only or read and change.
codex mcp add metarun --url https://metarun.dev/api/mcp02 · Sign in again later
If the sign-in expires or you disconnected it in MetaRun's settings. --no-browser prints the link instead, for SSH sessions.
codex mcp login metarun03 · Or edit ~/.codex/config.toml
The Codex CLI, the IDE extension and Codex in the ChatGPT desktop app read the same file, so one entry covers all three.
[mcp_servers.metarun]
url = "https://metarun.dev/api/mcp"Then ask Codex
- Ask Codex: Set 2.4 to release automatically after approval with a phased rollout.
- Ask Codex: Crash rate on 2.4 just doubled. Pause the phased release now and show me the last 20 reviews.
- Ask Codex: Everything looks fine after three days. Complete the phased release for 2.4.
codex exec runs one request without an interactive session and with its approval policy set to never. MetaRun's reads and previews still run, because they're marked read-only; anything that would ask is refused.
Read-only check, safe to schedule
codex exec "Report the state of the latest version of com.example.app and its phased release, including the current rollout day. Read only."Applies are refused in codex exec by design. Don't set MetaRun's approval mode to approve just to make them pass; keep App Store changes in an interactive session.
Cursor Anysphere
Add https://metarun.dev/api/mcp to ~/.cursor/mcp.json (or use the install link) and sign in to MetaRun when Cursor opens your browser.
01 · Add to ~/.cursor/mcp.json (or .cursor/mcp.json for one project)
{
"mcpServers": {
"metarun": {
"url": "https://metarun.dev/api/mcp"
}
}
}02 · Or use the install link
Opens Cursor with the server filled in.
https://cursor.com/link/mcp/install?name=metarun&config=eyJ1cmwiOiJodHRwczovL21ldGFydW4uZGV2L2FwaS9tY3AifQ%3D%3D03 · Sign in
When Cursor connects, MetaRun opens in your browser. Pick read-only or read and change, and you're back in the editor with the tools listed under MCP.
Then ask Cursor
- Ask Cursor: Change 2.4's release option to manual so we can launch with the blog post.
- Ask Cursor: Pause the 2.4 rollout while I look at this crash.
- Ask Cursor: Resume the phased release for 2.4.
The Cursor CLI runs one request without the editor with agent -p. Allow only the read tools the request needs in ~/.cursor/cli-config.json (Mcp(metarun:tool_name) rules), and keep MetaRun's apply tools out of that list.
Read-only check, safe to schedule
agent -p "Report the state of the latest version of com.example.app and its phased release, including the current rollout day. Read only." --output-format jsonDon't run it with --force for MetaRun: that approves every tool, applies included.
Xcode Apple
In Xcode 27, add the plug-in from https://github.com/metarun/metarun-skills (Settings, Intelligence, Plug-ins, Add from URL) and click Sign in next to MetaRun.
01 · Add the MetaRun plug-in
In Xcode 27, open Settings, Intelligence, Plug-ins. Choose Add Plug-in, then Add from URL, and paste:
https://github.com/metarun/metarun-skills02 · Or with one click
Opens Xcode's plug-in sheet with the repository filled in.
xcode://agent-plugin-clone?repo=https%3A%2F%2Fgithub.com%2Fmetarun%2Fmetarun-skills03 · Sign in
Install MetaRun from the list, then click Sign in next to it. MetaRun opens in your browser; pick read-only or read and change.
04 · Ask the coding assistant
Claude Agent, Codex and Gemini in Xcode all get MetaRun's tools and its six workflow skills.
Attach build 312 to version 2.4 and tell me what blocks submission.Then ask Xcode
- Ask Xcode: Schedule 2.4 to go live on 14 October at 09:00 UTC, with phased release.
- Ask Xcode: The fix in build 315 is in review. Pause the 2.4 rollout until it ships.
- Ask Xcode: 2.4 is approved and waiting. Release it now.
Claude Anthropic
In Claude, open Customize, Connectors, Add custom connector, paste https://metarun.dev/api/mcp and click Connect to sign in to MetaRun.
01 · Add a custom connector
In Claude, open Customize, then Connectors, and choose Add custom connector. Name it MetaRun and paste the server URL:
https://metarun.dev/api/mcp02 · Connect
Click Connect. Claude opens MetaRun in your browser to sign in; pick read-only or read and change.
03 · Team and Enterprise
An Owner adds the connector once under Organization settings, Connectors. Each member then clicks Connect and signs in to their own MetaRun account.
Then ask Claude
- Ask Claude: What's the release status of my latest version?
- Ask Claude: Pause the phased rollout. Some users are reporting a crash.
- Ask Claude: Release version 2.4 now. It's been approved.
Frequently asked questions
What are the App Store phased release percentages?
1% on day 1, 2% on day 2, 5% on day 3, 10% on day 4, 20% on day 5, 50% on day 6 and 100% on day 7, of users with automatic updates turned on. Apple picks them at random.
How long does phased release take?
Seven days if you never pause. Paused days don't count toward the seven, and pauses can add up to 30 days. Release to All Users ends it early.
How do I pause a phased release in App Store Connect?
Open the Ready for Distribution version, select Pause Phased Release in the Phased Release for Automatic Updates section and click Save. You have 30 days of pause in total across all pauses.
What's the difference between phased release and manual release?
Manual release decides when the approved version goes live: only when you click Release This Version. Phased release decides how quickly automatic updates reach existing users after that. You can use either one or both.
Can I roll back an App Store release?
No. Once a version is live there's no way to restore the previous one. Pause the phased release to stop automatic updates, then ship a fixed version, with an expedited review request if the bug is critical.
Does phased release apply to new downloads?
No. New downloads and manual updates get the new version from day 1. Only automatic updates follow the percentage schedule.
Can your agent pause a phased release?
Yes. apple_preview_phased_release covers start, pause, resume, complete and cancel. The apply runs after you approve it in your agent, and it refuses if the rollout's state changed since the preview.
Can I schedule a release for a specific date?
Yes, before you submit: set the release option to scheduled with an earliest release date. Apple releases on or after that date once the version is approved.
Can MetaRun roll back a release?
No, and neither can Apple. A released version stays released. You can pause a phased rollout to stop automatic updates while you ship a fix.
Is this different from releasing in App Store Connect?
It's the same Apple API calls behind the same buttons. The difference is that your agent reads the state first, previews the transition, and every change is recorded in your history.
Sources
Related guides
Guide
The pre-submission checklist, every review status, export compliance, rejections and expedites.
Guide
What's New and promotional text: the limits, when each one locks, examples for every kind of update, and what App Review rejects.
Guide
Internal vs external testers, Beta App Review, public links, and every reason testers see no builds.
Guide
Respond to App Store reviews: who can reply, editing and deleting, Apple's rules and reply templates.
All guides
Releases, TestFlight, pricing, subscriptions, localization, screenshots and more.
With MetaRun: App Store Connect MCP server
MetaRun
Do this from your AI agent or MetaRun's dashboard, with a preview before every change. 14-day free trial, no card.