agentleFS
RonenMarsRonenMars/threadbase-mobile/.agents/skills/ship-fastlane/SKILL.md

ship-fastlane

Skill4 starsChanged 2 days agoMITView on GitHub

Vanilla fastlane TestFlight pipeline. ONLY invoke this skill when the user explicitly types /ship-fastlane. Never trigger automatically on "ship", "TestFlight", or general release requests — those go to /expo-local-ship instead. Use when shipping from a machine without the maintainer signing env vars, when wiring up CI, or as a vanilla fallback if /expo-local-ship is misbehaving. Before running `bundle exec fastlane beta`, confirm with the user and wait for explicit approval.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Only when the user explicitly types /ship-fastlane.

    line 22
  2. Distinctive:

    Do not invoke on:

    line 24
  3. Very specific:

    If a user asks "should I ship?" or "how do I ship?", point them at docs/deployment.md and let them pick a path.

    line 30
  4. Very specific:

    Commit or stash the changes first.

    line 129

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Ship via Fastlane

Standard fastlane setup for archiving the iOS app and uploading to TestFlight. TestFlight only — no App Store submission, no polling until VALID, no custom signing bootstrap. The lane is intentionally minimal; if you need the full pipeline, use /expo-local-ship.

When this skill applies

Only when the user explicitly types /ship-fastlane.

Do not invoke on:

  • "ship", "ship it", "ship to TestFlight" — those go to /expo-local-ship.
  • "build", "archive", "upload" — same.
  • "fastlane" appearing in conversation context — wait for the explicit slash command.

If a user asks "should I ship?" or "how do I ship?", point them at docs/deployment.md and let them pick a path.

Project quick reference

KeyValue
Workspaceios/$APP_SCHEME.xcworkspace
Schemefrom $APP_SCHEME env var
Bundle IDfrom $APP_BUNDLE_ID env var
Marketing versionread from app.json → expo.version
Build numberderived from App Store Connect on every run
Signingautomatic, via ASC API key
OutputTestFlight (no App Store submission)

Prerequisites

  1. Ruby + bundler — System Ruby on macOS is fine. gem list bundler should show something.
  2. App Store Connect API key — .p8 file with the App Manager role, downloaded once from https://appstoreconnect.apple.com/access/integrations/api. Store outside the repo (~/.appstoreconnect/keys/ recommended).
  3. fastlane/.env — local, gitignored. Copy from fastlane/.env.example and fill in:
    • APP_BUNDLE_ID
    • APP_SCHEME
    • APPLE_TEAM_ID
    • ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_PATH
  4. bundle install — once per fresh clone. Installs fastlane into vendor/bundle/ (gitignored).
  5. ios/ directory present — either persistent or generated by a prior npx expo prebuild --platform ios. The lane does not run prebuild.

Daily command

bundle exec fastlane beta

That's the whole thing. Don't pass extra flags unless you know why.

What the lane does (in order)

  1. Pre-ship checks — shells out to ./scripts/git-sync-check.sh. Fails fast if:

    • app.json has uncommitted edits (we don't ship from a dirty tree).
    • Local main is behind origin/main (another machine may have pushed a build-number bump).
    • On a non-main branch, prints a warning but proceeds.

    See .Codex/skills/_shared/pre-ship-checks.md for the rationale behind these checks. They mirror the gates ./scripts/ship-ios.sh runs.

  2. Authenticate to ASC — app_store_connect_api_key with the three ASC_* env vars. No Apple ID prompt, no 2FA.
  3. Determine next build number — latest_testflight_build_number for the current marketing version, then + 1. ASC is the source of truth.
  4. Write build number into app.json (for Info.plist regeneration after a future expo prebuild) and directly into ios/$APP_SCHEME/Info.plist (used by the in-flight archive).
  5. Archive + sign + export — build_app with the inline export_options hash (teamID, signingStyle: automatic, symbols), passing ASC API key flags via xcargs so xcodebuild can refresh provisioning profiles non-interactively.
  6. Upload to TestFlight — upload_to_testflight with skip_waiting_for_build_processing: true. Returns as soon as the upload completes; ASC processing finishes asynchronously.
  7. Restore app.json — git restore app.json. The build number that was written in step 4 was derived data for this archive only; committing it would create churn. Working tree returns to clean.

What the lane does NOT do

MissingWhat to use instead
Maintainer signing env bootstrap./scripts/ship-ios.sh (Path A in docs/deployment.md)
expo prebuild if ios/ is missingRun npx expo prebuild --platform ios first, or use ship-ios.sh
Poll ASC until the build is VALIDCheck TestFlight manually, or use ship-ios.sh
Submit for App Store reviewship-ios.sh --target production
Auto-install npm dependenciesRun npm install (or your package manager) first

After a successful run

Nothing to commit. app.json was restored by step 7. git status will be clean.

The uploaded build appears on TestFlight after ASC processing finishes — usually 5–30 minutes. You can refresh the TestFlight tab in App Store Connect, or query the ASC API.

Troubleshooting

Error packaging up the application

You're missing one or more of the export config pieces. Verify:

  • APPLE_TEAM_ID is set in fastlane/.env.
  • ASC_KEY_PATH points at a .p8 file that actually exists (ls $ASC_KEY_PATH).
  • The Xcode project's signing is set to Automatic (the lane doesn't override this — whatever the project says, applies).

Error setting value 'app-store-connect' for option 'export_method'

This means someone changed export_method: in the Fastfile to app-store-connect. Fastlane only accepts the legacy app-store. Revert to export_method: "app-store".

Lane refuses to run because main is behind origin/main

Another machine (or you, on another laptop) pushed commits since you last pulled. Run:

git checkout main
git pull --ff-only

Then re-run the lane. This is intentional — see _shared/pre-ship-checks.md.

Lane refuses to run because app.json is dirty

Commit or stash the changes first. If your dirty app.json is just the lane's own previous write that wasn't restored (e.g. the lane crashed before the cleanup step):

git restore app.json

Missing env var

ENV.fetch("APP_BUNDLE_ID") (or similar) raised KeyError. Check fastlane/.env against fastlane/.env.example — make sure every required field is filled in.

Anti-patterns

  • Don't pass --no-build or --no-upload flags to skip parts of the lane. Either the whole thing runs or you're not actually shipping.
  • Don't commit app.json after a run. The lane already restored it; if you see "modified: app.json" in git status after the lane finished, something went wrong with step 7 — fix that rather than committing the bump.
  • Don't add new lanes for "staging," "preview," etc. without a clear scope. The simplicity is the point. Use fastlane/.env.production / .env.staging for environment switching, not new lanes.
  • Don't auto-fire on "ship" — that's /expo-local-ship's job. Read the trigger boundary at the top of this file.

See also

  • docs/deployment.md — full comparison of ship paths (this skill is Path B).
  • fastlane/Fastfile — the lane source.
  • fastlane/.env.example — env var template.
  • _shared/pre-ship-checks.md — canonical pre-ship policy.
  • /expo-local-ship — full pipeline (signing bootstrap, polling, production submission).
  • /ship-expo-cloud — EAS cloud builds (opt-in, costs money).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.