Configuration Reference

All config file keys, environment variables, and CLI flags.

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  >  config file  >  Built-in defaults

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

app:
app_store_connect:
code_signing:
build:
archive:
export:
testflight:
screenshots:
metadata:
versioning:
notifications:
workflows:
# 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.

build

archive

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.

version action options

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

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.

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.

notifications.slack

workflows

workflows:
  <workflow-name>:
    - action: <action-name>
      options:
        key: value

Each step:

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

swift run shipit ai-bootstrap --goal beta
swift run shipit schema --output json
swift run shipit inspect project --output json
swift run shipit suggest-config --goal beta --output json
swift run shipit validate yml --shipfile ./Shipfile.yml --output json

ai-bootstrap 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.

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.

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.

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_track maps to the Play Console track you are targeting: 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

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:
  app:
    scheme: MyApp
  archive:
    export_method: app-store