launchseq releases an iOS app in two stages:
launchseq countdown tests → version bump → App Store screenshots → release notes → release PR
launchseq liftoff CI gate → tag → Xcode Cloud build → website pages → App Store Connect
Liftoff stops once the App Store version is ready. You check it in App Store Connect and press Submit for Review yourself.
It's built for apps that:
- build in Xcode Cloud, with a workflow that starts when a tag is pushed and distributes to TestFlight
- keep their App Store copy in the repo as plain text files
- can open on a given screen from a launch argument, so screenshots are taken from fixed states instead of by playing the app
Each app describes itself in a .launchseq.yml. There's nothing app-specific in the tool.
Install a tagged release, not main. launchseq pushes tags and edits your App Store Connect versions, so pin a version you've read the notes for. The examples below use 0.2.0; swap in the latest release.
git clone --branch 0.2.0 --depth 1 https://github.com/Ceri-anne/launch-sequence.git
cd launch-sequence
swift build -c release
cp .build/release/launchseq /usr/local/bin/Any folder on your PATH works. Check with echo $PATH: a fresh Mac often has no ~/bin, /usr/local/bin may need sudo or not exist yet, and on Apple silicon with Homebrew, /opt/homebrew/bin is already on it and yours to write to. Run launchseq --version to confirm.
If you use Mint, it does the same build for you:
mint install Ceri-anne/launch-sequence@0.2.0To upgrade, read the new release's notes, then repeat either install with the new tag.
You'll need Xcode, git, and the GitHub CLI signed in (gh auth login).
The App Store Connect API key is read from the first place it's found:
-
The environment:
ASC_KEY_ID,ASC_ISSUER_ID, andASC_KEY_PATH(the path toAuthKey_<id>.p8) orASC_KEY_P8(the key's contents). -
~/.config/launchseq/credentials. It must bechmod 600, and launchseq refuses to read it otherwise.key_id = ABC123DEF4 issuer_id = 00000000-0000-0000-0000-000000000000 key_path = ~/.secrets/AppStoreConnect/AuthKey_ABC123DEF4.p8
-
For the private key only, the login Keychain:
security add-generic-password -s launchseq -a ABC123DEF4 -w "$(cat AuthKey_ABC123DEF4.p8)"
The key needs the Admin role if Xcode Cloud has to create signing certificates. App Manager is enough for everything launchseq itself does.
To have release notes translated, set ANTHROPIC_API_KEY. Without it, the other locales get TODO stubs, and countdown won't continue until they're filled in.
With Claude Code, the setup-launchseq skill walks through the steps below. It also covers the choices they leave open: which languages to list, which simulator to pin, and where the website pages and listing text get edited from now on. Install it once:
claude plugin marketplace add Ceri-anne/launch-sequence
claude plugin install launchseq@launch-sequenceThen, in the app's repo, ask Claude to set it up with launchseq.
By hand:
-
Run
launchseq initin the app's repo. It drafts.launchseq.ymlfrom the project (or XcodeGen'sproject.yml), the file holdingMARKETING_VERSION, the bundle ID and the newest iPhone Pro simulator, and lists anything it had to guess. Add your languages, and the optional sections you use.examples/launchseq.ymlis a complete config to copy from.launchseq init --dry-runprints the draft without writing it. -
Move the App Store copy into
<metadata_dir>/<asc-locale>/, one file per field:AppStoreAssets/metadata/ support_url.txt shared by every locale (a locale folder can override it) privacy_url.txt marketing_url.txt en-GB/name.txt max 30 en-GB/subtitle.txt max 30 en-GB/promotional_text.txt max 170 en-GB/keywords.txt max 100, comma-separated, no spaces after commas en-GB/description.txt max 4000 en-GB/release_notes.txt max 4000, "What's New"If the copy lives in Markdown with headings like
### Subtitle (max 30)and a fenced block under each,launchseq migrate-copy Copy.md:en Copy-Localized.mdconverts it. It leaves out "What's New", because that belongs to one release: the next countdown drafts it. -
Put the support, privacy and accessibility pages in the folder
website.sourcenames. That folder is the source, and the website copy is the output. -
Set up the Xcode Cloud Release workflow that
liftoff's tag push starts. Edit it in Xcode (Integrate → Manage Workflows), not the App Store Connect web editor: when the.xcodeprojis generated and gitignored, the web editor can't list the schemes.- Start condition: Tag Changes with Any Tags. Custom Tags only take exact tag names or a prefix such as
release/*, so a glob like*.*.*is read as one literal tag name and never matches. Any Tags is safe as long asliftoffis the only thing that pushes tags. - Add a second start condition, Manual Start → Tag. A tag that was pushed before the trigger worked doesn't build when you fix it, and this lets you build it by hand (Start Build, pick the tag) instead of re-pushing it.
liftoffwaits for that build and attaches it. - Action: Archive for iOS, with Distribution Preparation set to TestFlight and App Store. A build prepared for internal testing only can't be submitted for review.
- Start condition: Tag Changes with Any Tags. Custom Tags only take exact tag names or a prefix such as
-
Run
launchseq doctor.
launchseq countdown # minor bump: 1.1.0 → 1.2.0
launchseq countdown --bump patch # or major
launchseq countdown --set-version 2.0.0
launchseq countdown --dry-run # show the plan, change nothing- Checks that the tree is clean, then fetches. The only changes it allows are countdown's own output (the version file, release notes, screenshots) from an unfinished run of the same version, on its release branch. The latest
X.Y.Ztag is the source of truth for the current version, and other tag shapes are ignored. IfMARKETING_VERSIONis already ahead of the bumped tag, the larger version is used. - Checks the App Store copy against Apple's limits before anything slow runs.
- Creates
release/<version>fromorigin/main. If the branch already exists, countdown carries on with it only if it starts from the latestorigin/mainand holds nothing but countdown's own commits. Countdown never amends a commit; a re-run adds a new one. - Runs the test suite on the simulator from the config. It needs an exact OS version, because several runtimes can share a device name.
- Bumps
MARKETING_VERSIONeverywhere it appears inversion.file. - Builds Debug apps and captures every language × device × scene. If a device has a
before:step (such as unfolding a simulator in Device Hub), countdown waits for you. Then it runs the app'srenderhook and checks every rendered image against the slot's accepted pixel sizes. With--skip-screenshots, or when the captures are already done, it skips capturing but renders again if any raw capture is newer than the framed images. - Drafts English release notes from the commit subjects since the last tag and opens them in
$EDITOR. Once you've saved them, Claude translates them into each other locale, using that locale's description as a guide to tone. Countdown refuses to ship notes that haven't changed since the last release, unless you pass--reuse-notes. - Warns if files matching
privacy_sensitive_pathschanged but the website pages didn't. - Commits and opens a release PR. Review the screenshots and translations there, then Rebase and merge.
--directpushes to the base branch instead.
Progress is saved in .git/launchseq/state.json, so a re-run skips the steps that are already done. --fresh starts over.
Run this on an up-to-date main after the release PR has merged:
git switch main && git pull --rebase
launchseq liftoff --dry-run # reads App Store Connect, changes nothing
launchseq liftoff- Reads the version from
main, and checks the copy and screenshots. - Requires green CI checks (Xcode Cloud reports them to GitHub) on the release commit. It waits up to 5 minutes for checks to register, then for them to finish. If none register, it looks for an Xcode Cloud build of the commit in the
app_store.ci_workflowworkflow (Mainby default) and, if there isn't one, offers to start it onmain.--forceskips the wait and carries on whatever the checks say. - After confirming with you, pushes an annotated tag, which starts the Xcode Cloud Release build. It also creates a draft GitHub release.
- Copies the website pages into a temporary clone of the site repo and, if they've changed, opens a PR. It waits for the PR's checks to register and finish, and asks before merging. If no checks register, it says so and asks whether to merge anyway.
- In App Store Connect: creates or reuses the version, sets the release type and phased release, and updates the name, subtitle, privacy URL, description, keywords, promotional text and What's New in every locale. It replaces the screenshots that changed, one at a time: each is uploaded and processed by Apple before the next starts, and a re-run keeps the ones at the start of a set that are already right. Then it waits for the build to finish processing, attaches it, and sets TestFlight's What to Test text.
- Publishes the GitHub release and prints a summary with a link to the App Store Connect version.
Every step checks what's already there, so if liftoff stops partway (a network error, a slow build), run it again.
Dragging screenshots into App Store Connect can be more reliable than uploading them through the API. To do it that way, set upload: manual in the screenshots section, or pass --manual-screenshots to liftoff. Liftoff then never uploads or deletes screenshots. For each locale and display type that doesn't already match the local files, it:
- Copies that slot's framed screenshots into
build/launchseq/upload/<locale>/<display type>/and opens the folder in Finder. If a slot is filled from several devices, the files are renamed1-<device>-<scene>.png,2-…, so Finder lists them in upload order. - Asks you to delete what's in that slot and drag the files in, in the order it lists.
- When you press Enter, checks the set against the local files: the same names in the same order, and the same images (by checksum, or file size if App Store Connect has no checksum). It lists anything that's wrong and asks you to fix it, then waits up to 30 minutes for Apple to finish processing.
- No secrets in config. API tokens live in memory only, are valid for 15 minutes, and are sent only to
api.appstoreconnect.apple.com. Screenshot uploads go to Apple's pre-signed upload URLs, without the token. - Commands are run directly with an argument list, never through a shell.
- Config paths must stay inside the repo, and unknown config keys are errors.
- Pushing the tag, opening PRs, merging the website PR and renaming an App Store version all ask first, unless you pass
--yes. --dry-runruns every read for real and prints every write instead of doing it.
See SECURITY.md to report a vulnerability.
swift build
swift test