Configuration Reference

Shipfile.yml is only the default config filename. ShipIt reads ./Shipfile.yml when --shipfile is omitted, but any YAML file path works with --shipfile <path>.

For config-backed CLI commands, the selected file must exist. A missing ./Shipfile.yml or missing --shipfile <path> target causes the command to exit with code 2.

Priority Order

CLI flags  >  SHIPIT_* env vars  >  .env file  >  config file  >  Built-in defaults

.env file auto-loading

ShipIt automatically loads a .env file from the same directory as Shipfile.yml before resolving configuration. Variables already in the process environment take precedence and are never overwritten.

Supported formats: KEY=VALUE, export KEY=VALUE, quoted values, and # comments. Use shipit generate to create a pre-populated .env file; it is automatically added to .gitignore.

Environment variable naming convention

Shipfile YAML keys map to env vars by upper-casing and joining path segments with _, prefixed with SHIPIT_. Nested keys use __ (double-underscore) as the section separator.

Secrets bypass: ASC_KEY_ID, ASC_ISSUER_ID, ASC_PRIVATE_KEY, ASC_PRIVATE_KEY_PATH, and VAULT_PASSWORD are also read directly (without the SHIPIT_ prefix) for compatibility with standard CI secret naming.

Top-Level Structure

platform:
app:
app_store_connect:
code_signing:
build:
archive:
export:
testflight:
screenshots:
metadata:
versioning:
project_generation:
notifications:
test_workflow:
workflows:
custom_actions:
# Platform-specific overrides (merged on top of shared config)
ios:
android:

app

Where to find these values manually:

• bundle_id: your target's bundle identifier / application ID in Xcode Signing settings or PRODUCT_BUNDLE_IDENTIFIER in build settings
• team_id: the 10-character Apple Developer Team ID for the team selected in Xcode Signing, also shown in the Apple Developer account / Certificates, IDs & Profiles

app_store_connect

For App Store Connect API actions, provide key_id, issuer_id, and exactly one private key source: private_key or key_path.

issuer_id is not inside the .p8 file. Copy it from the App Store Connect API Keys page.

You can omit this whole section if you only use local Xcode actions such as build, test, archive, or export.

Find these values in App Store Connect:

1. Open Users and Access.
2. Open Integrations.
3. Open App Store Connect API.
4. Create or select an API key.
5. Copy Key ID and Issuer ID.
6. Download the .p8 file and use it via private_key or key_path.

If ShipIt cannot infer app.team_id, use the team selected in Xcode for the app target. The value you need is the Apple Developer Team ID, not the App Store Connect issuer ID.

code_signing

Set VAULT_PASSWORD env var for the encrypted repo passphrase.

With type: automatic, ShipIt passes -allowProvisioningUpdates to Xcode build/export operations and writes signingStyle=automatic into export options.

With type: manual, shipit sign sync installs the configured .p12 certificate and provisioning profile. Local paths are preferred when they exist; base64 values are used as a CI fallback.

build

archive

Top-level archive keys apply to iOS archives. Android archive options are set per workflow step (see archive action options).

export

testflight

screenshots

metadata

versioning

ShipItSwifty follows Apple's two-version model:

The versioning section controls how CFBundleVersion is incremented. CFBundleShortVersionString is only changed when the version action is called with bump: major, bump: minor, or bump: patch.

source: pubspec (Flutter)

Flutter treats the pubspec version: key as the single source of truth: flutter build stamps CFBundleShortVersionString, CFBundleVersion, versionName, and versionCode from it on every build, so bumping the native project files directly wouldn't stick. pubspec is already the default source when the resolved build system is Flutter. Set it only to override the file location:

versioning:
  source: pubspec # default for build_system: flutter
  spec_path: pubspec.yaml # optional; defaults to pubspec.yaml at the project root

The part before + is the marketing version and the part after is the build number, so version: 1.2.3+45 reads as marketing 1.2.3, build 45. With no +build suffix the build number reads as 0, and the first bump: build writes +1. Only the top-level version: key is rewritten; comments and the rest of the file are preserved.

version action options

The version action accepts a bump option that selects which counter to change:

Version dry-run preview

Use --dry-run to see the computed before/after version values without writing anything:

shipit version --bump build --dry-run
shipit version --bump patch --dry-run --output json

Safe bump ordering

When a workflow bumps the marketing version (patch/minor/major) and the build number in the same run, place the marketing version bump first. A marketing version bump resets the build number to 1, so running it after a build bump would discard the incremented value. Pair each version step with an immediate git commit so a late-stage failure leaves a clean rollback target.

workflows:
  beta:
    - action: test
    - action: archive
    - action: version # bump only after build succeeds
      options: { bump: build }
    - action: git # commit immediately so git is the rollback mechanism
      options:
        operation: commit # stages all changes (git add -A) then commits
        commit_message: "chore: bump build number [skip ci]"
    - action: export
    - action: testflight

The git action's operation: commit stages every change in the working tree (git add -A) before committing — there is no per-file option. In CI this is usually what you want, since the runner starts from a clean checkout and the only modified files are the version bump. If you have unrelated local changes, commit or stash them first.

Beta workflow pattern (local-only, Apple semantics)

For a local beta that increments the build number, runs tests, then archives and exports:

versioning:
  strategy: sequential # CFBundleVersion stays a plain integer
  source: xcodeproj # reads/writes MARKETING_VERSION + CURRENT_PROJECT_VERSION in .xcodeproj
 
workflows:
  beta:
    - action: version
      options:
        bump: build # increments CFBundleVersion only; marketing version unchanged
    - action: test
      options:
        destinations:
          - "platform=iOS Simulator,name=iPhone 16 Pro,OS=18.2"
        retry_on_failure: true # retry each failing test once before surfacing a failure
        # only_testing:           # narrow to specific targets, e.g. [NovalingoTests/CoreTests]
        # skip_testing:           # skip slow targets, e.g. [NovalingoUITests]
    - action: archive
    - action: export # exports IPA locally; no upload to App Store Connect

Use xcodebuild -showdestinations -scheme <Scheme> (or shipit ai session --goal local) to discover destination strings that are valid on your machine before filling in the destinations array. You can list multiple destinations to run tests on several simulators or devices in one step.

How source: xcodeproj is resolved:

1. xcodebuild -showBuildSettings — reads MARKETING_VERSION and CURRENT_PROJECT_VERSION directly from Xcode build settings. This is the primary path for modern Xcode projects.
2. xcrun agvtool — fallback for projects that have VERSIONING_SYSTEM = apple-generic but not the newer MARKETING_VERSION key.
3. plutil on Info.plist — last resort for legacy projects.

To add a TestFlight upload later, append a testflight step and uncomment the app_store_connect section.

test action options

The test action is configured inline in a workflow step. It does not have a top-level Shipfile section.

Three options retry tests, and they solve different problems:

• retry_on_failure passes xcodebuild's built-in -retry-tests-on-failure for a one-pass iOS retry.
• rerun_failed_tests is ShipIt's own selective rerun. It collects the failures, reruns only those tests, and reports flaky versus persistent failures in the TestRunReport.
• infrastructure_retry reruns the whole invocation after a transient tool, simulator, or emulator failure — a simulator launch crash, an Android emulator disconnect, a Flutter tool crash, or a JS worker failure.

The last two have separate budgets. An infrastructure retry never spends a rerun attempt, and a selective rerun never spends an infrastructure attempt. Each execution is recorded as its own attempt in the report.

shipit generate asks whether generated test steps should enable infrastructure_retry. shipit ai session includes the same guidance in the agent prompt so AI-assisted workflow creation asks the same question.

Every test run writes a TestRunReport (schema version 2). See Test Results & Workflows for what it contains.

Native iOS: build once, test many

By default ShipIt builds the tests once into an .xctestproducts bundle, then runs every plan and destination with test-without-building, writing a separate result bundle for each. Retries reuse the same products.

workflows:
  tests:
    - action: test
      options:
        test_plans: [Unit, UI]
        destinations:
          - "platform=iOS Simulator,name=iPhone 17"
        rerun_failed_tests: { enabled: true, max_attempts: 2 }
        infrastructure_retry: { max_attempts: 3, initial_delay_seconds: 2, max_delay_seconds: 30 }

• Plans run independently. A failing plan doesn't stop the others, but a failed shared build blocks all of them.
• Each plan and destination is its own entry in the report's destinations, carrying that configuration's language and region.
• If xcodebuild reports a simulator clone failure, ShipIt falls back to serial execution once per destination without rebuilding. Ordinary assertion failures never trigger the fallback.
• Set legacy_combined_test: true to keep the older single xcodebuild test invocation.
• Select a test workflow by name with the top-level test_workflow key. See Test workflows.

Destination string format

platform=iOS Simulator,name=<SimulatorName>,OS=<Version>
platform=iOS,name=<DeviceName>
platform=macOS

Run xcodebuild -showdestinations -scheme <Scheme> (with -workspace or -project as appropriate) to list all valid destination strings for your scheme on the current machine. Alternatively, run shipit ai session --goal local which calls destination discovery automatically and includes the results in nextQuestion so an AI agent can ask which destinations to use.

Android examples:

workflows:
  beta:
    steps:
      # JVM unit tests for a single module
      - action: test
        options:
          kind: unit
          build_variant: debug
 
      # Instrumented tests — defaults to scope:root for multi-module projects
      - action: test
        options:
          kind: instrumented
          devices:
            strategy: named_emulators
            emulators: [Pixel_9_API_35]
 
      # Explicit root-level aggregate task
      - action: test
        options:
          task: testDebugUnitTest
          scope: root

For Android aggregate tasks, ShipItSwifty falls back to JUnit XML reports under build/test-results/<taskName>/ when Gradle stdout does not include a test summary.

swift-test and swift-format actions

SwiftPM packages use two dedicated actions, which are ordinary workflow steps. Select a test workflow with the top-level test_workflow key (or SHIPIT_TEST_WORKFLOW); shipit test --workflow <name> overrides it.

test_workflow: tests
workflows:
  format:
    - action: swift-format
      options: { paths: [Sources, Tests] }
  tests:
    - action: swift-test
      options:
        enable_code_coverage: true
        rerun_failed_tests: { enabled: true, max_attempts: 2 }
        infrastructure_retry: { max_attempts: 3, initial_delay_seconds: 2, max_delay_seconds: 30 }

swift-test saves Swift Testing events, attachments, stdout/stderr, and a final report.json.

swift-format is strict and non-mutating: it lints and never rewrites files.

Packages that import UIKit

A package whose sources import a framework the host lacks, such as UIKit, without a canImport or os(...) guard can't run under swift test. shipit inspect project --output json reports this under swiftPackage, and shipit generate --goal local (or shipit ai session --goal local) suggests a test step instead of swift-test. That step uses the scheme Xcode generates for the package directory — the package name when it has at most one product, <name>-Package when it has several — and runs xcodebuild on a simulator without app.project or app.workspace.

test-results action options

Use test-results to read test-result artifacts without running tests: xcresult bundles, JUnit XML (Gradle, KMP, and swift test), Swift Testing events, Flutter machine events, Jest JSON, and ShipIt reports or portable exports. Explicit inputs work without a Shipfile. The options below follow the schema printed by shipit schema --output json.

The CLI flags don't map one to one onto these keys: on the command line, --report is the JUnit directory (the action's report_path), and --report-path is where the JSON report is written (the action's report_output_path).

Archive action options

The archive action accepts inline step options for both iOS and Android:

project_generation

Configuration for automatic project file generation (XcodeGen, Tuist) before Xcode-dependent steps.

When project_generation.tool is configured, Workflow.run() automatically generates the Xcode project before the first Xcode-dependent step (build, test, archive, etc.), including steps reached through nested custom_actions. Generation is skipped when the output project already exists.

notifications.slack

workflows

Workflows can be defined as a plain array of steps (legacy) or as an object with optional workflow-level overrides:

# Legacy format: plain array of steps
workflows:
  beta:
    - action: archive
    - action: testflight
 
# New format: object with workflow-level overrides
workflows:
  release:
    build_variant: prodRelease
    steps:
      - action: archive
      - action: play-store
        options:
          track: production

Workflow-level overrides

Each step:

Use these AI-oriented commands to inspect the supported workflow surface:

swift run shipit ai session --goal beta
swift run shipit schema --output json
swift run shipit inspect project --output json
swift run shipit generate --goal beta
swift run shipit validate yml --shipfile ./Shipfile.yml --output json

ai session always emits JSON and is intended for AI/tooling integrations rather than direct human consumption.

Workflow notes:

• export can write an IPA into export.output_directory.
• testflight and upload can reuse that exported IPA automatically when they run after export in the same workflow and no explicit ipa / ipa_path is set.
• validate reports an error when testflight or upload has no explicit IPA and no prior export context.

Test workflows and artifacts

A test workflow is an ordinary workflow made of test steps. The top-level test_workflow key (or SHIPIT_TEST_WORKFLOW) names the one shipit test runs by default, and shipit test --workflow <name> picks one explicitly. Workflow selection is exclusive with direct test options.

test_workflow: tests
workflows:
  tests:
    continue_on_failure: true # workflow-level: run the tests even if formatting fails
    steps:
      - action: swift-format
      - action: swift-test
        options:
          output_directory: "build/results/{{run_id}}"
        artifacts:
          - name: results
            paths: ["build/results/{{run_id}}"]
            retention_days: 14

artifacts declares files a step produces that should be published with the run.

• name uses letters, numbers, underscores, and hyphens. paths takes files, directories, or globs (*, ?, and **), and retention_days is 1–90.
• Test runs already keep their evidence under build/workflow-artifacts/<run_id>/, which is staged and uploaded as a whole. Declare artifacts only for files a step writes elsewhere.
• Report and result locations a step publishes (report_path, output_directory, result_bundle_path) are collected automatically. Build products such as IPAs, AABs, APKs, and archives are never collected unless you list them.
• Evidence is gathered after a failed step too. A missing optional match becomes a diagnostic, not a failure.

continue_on_failure: true is a workflow-level key, set next to steps in the object format. It is opt-in, for independent checks that should all run. The default stays fail-fast, and any failed step still makes the whole workflow fail. Only artifacts (and when) go on an individual step.

{{run_id}} resolves to the current workflow run's ID in a step's options and artifact paths, keeping the output of separate runs apart. It is available to top-level steps only. See Workflow tokens & step conditions.

Turn a test workflow into a CI job with shipit ci export.

firebase-app-distribution action options

Use the firebase-app-distribution workflow action to upload a signed IPA, APK, or AAB to Firebase App Distribution. It accepts credentials only from an environment variable or a local service-account file; never put service-account JSON in Shipfile.yml.

The action resolves credentials in this order: service_account_path, FIREBASE_SERVICE_ACCOUNT_JSON (raw JSON), then GOOGLE_APPLICATION_CREDENTIALS (path to a service-account JSON file). The Firebase app ID platform is checked against the artifact before upload, so an iOS app ID requires an IPA and an Android app ID requires an APK or AAB.

workflows:
  beta:
    - action: archive
    - action: export
      options:
        output_directory: ./build/firebase
    - action: firebase-app-distribution
      options:
        app_id: ${FIREBASE_IOS_QA_APP_ID}
        artifact_path: ./build/firebase/MyApp.ipa
        groups: [qa-testers]
        release_notes: "Build {{build_number}}"

See Firebase App Distribution for setup and Android examples.

• Human output from shipit run <workflow> now prints per-step summaries when available, including test pass/fail/skip counts, version strings, and archive artifact filenames.

custom_actions

User-defined composite actions — reusable, parameterized sequences of built-in actions (or other custom actions). Use these to avoid duplicating step blocks across workflows (for example sharing test → archive → export between beta and adhoc).

custom_actions:
  <composite-name>:
    description: "Human-readable summary (optional)."
    parameters:
      <param-name>:
        type: string # string | bool | int | number | array | object | any
        required: true # defaults to true when no default is set
        default: <value> # optional fallback when call site omits the value
        description: "..."
    steps:
      - action: <registered-action-or-other-composite>
        options:
          <option>: "{{param.<param-name>}}"

Invocation is identical to a built-in action — a workflow step uses action: <composite-name> and forwards call-site values via its options: block:

custom_actions:
  build_and_sign:
    description: "Test, archive, and export the app with a chosen export method."
    parameters:
      method:
        type: string
        required: true
    steps:
      - action: test
      - action: archive
      - action: export
        options:
          method: "{{param.method}}"
 
workflows:
  beta:
    - action: build_and_sign
      options:
        method: app-store
    - action: testflight
  adhoc:
    - action: build_and_sign
      options:
        method: ad-hoc
    - action: notify

Parameter reference syntax: {{param.NAME}}

Inside a step's options: block, string values may reference declared parameters using {{param.NAME}}. This delimiter is chosen to stay out of the way of every common template system that surrounds a Shipfile:

Rules:

• Only string leaves in a step's options: are scanned. Keys and non-string scalars are untouched.
• When a string is exactly {{param.NAME}}, the underlying typed JSON value is substituted (bool, int, array, object). When it appears inline with other text, the value is stringified.
• Unknown parameter references cause shipit validate yml to report an error rather than silently expanding to an empty string.

Validation rules

shipit validate yml enforces:

• Custom action names must not collide with built-in action names.
• steps: must contain at least one step.
• Each step's action: must resolve to a built-in or another declared custom action.
• Each {{param.NAME}} reference inside a step's options must match a declared parameter.
• Required parameters must be supplied at the call site (or have a default:).
• The graph of composite-to-composite references must be acyclic.

AI-session integration

shipit ai session includes the user's custom actions in the generated agent prompt (name, description, and declared parameters). Agents are instructed to prefer invoking an existing composite over duplicating its step sequence in a new workflow.

Workflow tokens & step conditions

Top-level workflow steps support reserved interpolation tokens and an optional when: condition. Together they let a single shipit run bump the version, distribute, then commit and tag the release — no shell or jq glue required.

Reserved tokens

Rules:

• Tokens are substituted into string leaves of a step's options: and into its when: value, at run time.
• Values come from the most recent version step's result. Before any version step runs they are seeded best-effort from the current versioning source (and {{version_changed}} is false).
• {{run_id}} doesn't depend on a version step: it is generated when the workflow starts.
• An unknown or not-yet-resolved token is left literal (and logged) rather than expanding to empty.
• These are distinct from composite {{param.NAME}} references and from Shipfile ${ENV_VAR} expansion. Resolution is scoped to top-level workflow steps; tokens inside custom_actions substeps are not resolved in this release.

when: conditions

A step may carry when: "<expr>". Reserved tokens are substituted first, then the result is evaluated for truthiness: true, 1, or yes (case-insensitive) run the step; anything else — including an unresolved literal token — skips it (recorded with status skipped; the workflow continues). v1 supports a single truthy token, not operators or comparisons.

Skips and workflows marked continue_on_failure: true are the only exceptions to fail-fast workflow semantics. Any other failing step still aborts the workflow, and a continue_on_failure workflow with a failed step still finishes as failed.

Example: tag the released version in one shipit run

workflows:
  release:
    - action: version
      options: { bump: patch } # or { bump: ${RELEASE_BUMP} } to drive from CI
    - action: archive
    - action: play-store
      options: { track: production }
    - action: git
      options:
        operation: commit
        commit_message: "chore: release v{{version}} (build {{build_number}})"
    - action: git
      when: "{{version_changed}}" # skipped on build-only bumps
      options:
        operation: tag
        tag_name: "v{{version}}"
    - action: git
      options:
        operation: push
        push_tags: true

shipit generate --goal release scaffolds this commit/tag/push tail for you — for both iOS and Android — and offers to drive the bump from CI via ${RELEASE_BUMP}. CI prerequisites the generator prints: a full-history checkout, write permission on the repo, and a configured git identity (user.name / user.email).

Environment Variables Summary

android

Platform-specific Android configuration. These values are merged on top of shared config when --platform android is active or the platform is auto-detected as Android.

AndroidCLI (preview, opt-in)

AndroidCLI complements the Gradle/ADB pipeline and does not build release artifacts. Use shipit android-cli for direct commands; workflow actions require explicit opt-in:

android:
  cli:
    enabled: true
    executable_path: android
    sdk_path: /opt/android-sdk

ShipIt requires AndroidCLI 1.0 or newer when enabled. It never downloads, initializes, updates, or installs skills automatically. Device- or environment-changing workflow operations require allow_mutation: true. AndroidCLI is preview software and may report basic command/option telemetry; emulator management is currently unavailable on Windows. | gradle_flags | array | [] | — | Extra Gradle flags such as --stacktrace |

Google Play credentials

Set these environment variables for Google Play upload actions:

Lookup notes:

• package_name is your Android applicationId, usually from app/build.gradle or app/build.gradle.kts
• play-store steps require a track option (or --track on the CLI) to target a Play Console track such as internal, alpha, beta, or production
• Create the service account in Google Cloud, enable the Google Play Developer API, then invite that service account in Play Console Users and permissions
• Give the service account Play Console permissions that match the rollout you want to perform

Env var naming: Android keystore variables support both the short form (ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_PASSWORD, ANDROID_KEY_ALIAS) and the standard SHIPIT_ form (SHIPIT_ANDROID__KEYSTORE_PASSWORD, SHIPIT_ANDROID__KEY_PASSWORD, SHIPIT_ANDROID__KEY_ALIAS). The short forms are checked as a compatibility fallback when the SHIPIT_ names are not set.

ios

Platform-specific iOS overrides. Merged on top of shared config when --platform ios is active. All top-level app, code_signing, archive, export, testflight, and screenshots keys can appear here to override the shared defaults for iOS only.

ios:
  build_system: native # native (default) | flutter | react_native | kmp
  scheme: MyApp
archive:
  export_method: app-store

Build systems

build_system is orthogonal to platform: a single Kotlin Multiplatform or Flutter source tree can produce both an iOS .ipa and an Android .aab.

Auto-detection

When build_system is unset, ShipItSwifty resolves it automatically:

Flutter

• iOS: flutter build ipa writes the IPA to build/ios/ipa/, so there is no separate export step. Omit export from a Flutter iOS workflow.
• Android: build runs flutter build apk; archive runs flutter build appbundle.
• Versioning: pubspec is the default versioning.source, because flutter build stamps the native projects from pubspec.yaml.
• Tests: test runs flutter test with machine output. Reruns select failed tests by name, and results report the flutter-test runner with buildSystem: flutter.

React Native

• iOS: archive runs xcodebuild archive on the Xcode project React Native or Expo generated, then export and testflight work as for a native app.
• Android: archive runs npx react-native build-android --tasks bundleRelease, falling back to a direct gradlew :app:bundleRelease on an Expo app without the React Native CLI.
• Tests and lint: test and lint run the package manager's test and lint scripts. Jest results are collected as JSON and support rerun_failed_tests.
• Run shipit from the directory that holds package.json. See the React Native Quickstart.

KMP example

ios:
  build_system: kmp
  scheme: iosApp
  workspace: iosApp/iosApp.xcworkspace
  kmp_shared_module: shared
  kmp_build_target: IosSimulatorArm64
  kmp_archive_target: IosArm64
android:
  build_system: kmp
  module: androidApp
  gradle_project_dir: .
versioning:
  source: kmp
  spec_path: gradle.properties

coverage action options

The coverage action reads coverage artifacts — it does not generate them. Without input_format it auto-discovers an iOS .xcresult or an Android JaCoCo report; with it, it reads a saved report from any supported tool. The options below follow the schema printed by shipit schema --output json.

A SwiftPM or LCOV file doesn't say where the tests ran, so its platform is unknown, and reports from different runs are never summed. Kotlin/Native and JavaScript coverage aren't available through these formats.

workflows:
  tests:
    - action: swift-test
      options: { enable_code_coverage: true }
    - action: coverage
      options:
        input_format: swift
        report_path: .build/debug/codecov/MyPackage.json
        source_roots: [Sources]
        exclude_previews: true
        minimum_coverage: 70