A GitHub Action that wraps xcrun xcodebuild to build, archive, and export an Xcode project or workspace. Designed to compose with the rest of the Apple-Actions suite:
Apple-Actions/import-codesign-certsApple-Actions/download-provisioning-profilesApple-Actions/upload-testflight-buildApple-Actions/notarize
See Apple-Actions/Example-macOS for a full macOS workflow that ships to TestFlight and as a notarized Developer ID DMG.
- uses: Apple-Actions/xcodebuild@v1
with:
workspace: ios/MyApp.xcworkspace
scheme: MyApp
sdk: iphonesimulator
build-number: ${{ github.run_number }}- id: build
uses: Apple-Actions/xcodebuild@v1
with:
workspace: ios/MyApp.xcworkspace
scheme: MyApp
sdk: iphoneos
action: archive
archive-path: .build/Archives/MyApp.xcarchive
export-options-plist: ios/ExportOptions.plist
build-number: ${{ github.run_number }}Split compile and XCTest into two steps in the same job so build failures and test failures show separately. Both steps share the default DerivedData (.build/DerivedData); override log-path or result-bundle-path only if you need distinct artifacts beyond the defaults.
- name: Build
uses: Apple-Actions/xcodebuild@v1
with:
project: App.xcodeproj
scheme: App
configuration: Debug
sdk: iphonesimulator
destination: platform=iOS Simulator,OS=latest,name=iPhone 17
action: build-for-testing
- name: Run Tests
uses: Apple-Actions/xcodebuild@v1
with:
project: App.xcodeproj
scheme: App
configuration: Debug
sdk: iphonesimulator
destination: platform=iOS Simulator,OS=latest,name=iPhone 17
action: test-without-buildingArchive once and export twice. The notarized DMG then holds the same binary you upload to TestFlight, and the dSYMs in the archive symbolicate crashes from both.
action: export runs only xcodebuild -exportArchive against an existing archive, so one archive can be exported with several methods. workspace and project aren't needed in this mode.
- id: build
uses: Apple-Actions/xcodebuild@v1
with:
project: App.xcodeproj
scheme: App
action: archive
archive-path: .build/Artifacts/App.xcarchive
export-options-plist: ExportOptions.plist # method: app-store-connect
build-number: ${{ github.run_number }}
- id: developer-id
uses: Apple-Actions/xcodebuild@v1
with:
scheme: App
action: export
archive-path: ${{ steps.build.outputs.archive-path }}
export-options-plist: ExportOptions-DeveloperID.plist
export-path: .build/Artifacts/developer-id
- uses: Apple-Actions/upload-testflight-build@v5
with:
app-path: ${{ steps.build.outputs.pkg-path }}
app-type: macos
backend: altool
issuer-id: ${{ vars.APPSTORE_ISSUER_ID }}
api-key-id: ${{ vars.APPSTORE_API_KEY_ID }}
api-private-key: ${{ secrets.APPSTORE_API_PRIVATE_KEY }}
# Package ${{ steps.developer-id.outputs.app-path }} into a DMG, then notarize it.Use the pkg-path and app-path outputs rather than hard-coding paths inside the export directories. See Apple-Actions/Example-macOS for the full workflow, including DMG packaging with notarize.
Example ExportOptions-DeveloperID.plist:
<dict>
<key>method</key>
<string>developer-id</string>
<key>provisioningProfiles</key>
<dict>
<key>com.example.app</key>
<string>DeveloperID com.example.app</string>
</dict>
<key>signingCertificate</key>
<string>Developer ID Application</string>
<key>signingStyle</key>
<string>manual</string>
<key>teamID</key>
<string>ABCDE12345</string>
</dict>In an App Store macOS ExportOptions.plist, installerSigningCertificate is 3rd Party Mac Developer Installer. Keychain Access shows the same certificate as "Mac Installer Distribution".
| Name | Description | Default |
|---|---|---|
workspace |
Path to the .xcworkspace. Mutually exclusive with project. Required unless action is export. |
— |
project |
Path to the .xcodeproj. Mutually exclusive with workspace. Required unless action is export. |
— |
scheme |
Scheme to build. Required. | — |
configuration |
Build configuration. | Release |
sdk |
SDK to build against (e.g. iphoneos, iphonesimulator, macosx). |
— |
destination |
Destination specifier, e.g. generic/platform=iOS. |
— |
action |
xcodebuild action: build, archive, test, build-for-testing, test-without-building, clean, or export. export only runs -exportArchive on an existing archive-path and requires export-options-plist. |
build |
archive-path |
Output path for the .xcarchive. Required when action is archive or export. |
— |
export-options-plist |
Path to an ExportOptions.plist. When set, the archive is exported. |
— |
export-path |
Export directory for the IPA. | <result-bundle-dir>/<scheme>.ipa |
derived-data-path |
Derived data directory. | .build/DerivedData |
result-bundle-path |
Path for the .xcresult bundle. |
.build/Artifacts/<scheme>.xcresult |
build-number |
Value passed as CURRENT_PROJECT_VERSION. |
— |
build-settings |
Additional KEY=VALUE build settings, one per line. |
— |
extra-arguments |
Additional arguments passed verbatim to xcodebuild. |
— |
output-formatter |
Command to pipe output through (xcbeautify, xcpretty, or empty). The default enables xcbeautify's github-actions renderer so compile errors/warnings surface as inline PR annotations. |
xcbeautify --renderer github-actions |
log-path |
Path to write the raw xcodebuild log. | .build/<scheme>-<action>.log |
parallelize-targets |
Pass -parallelizeTargets. |
true |
show-build-timing-summary |
Pass -showBuildTimingSummary. |
true |
disable-automatic-package-resolution |
Pass -disableAutomaticPackageResolution. |
true |
zip-result-bundle |
Zip the .xcresult bundle next to itself. |
false |
zip-archive |
Zip the .xcarchive next to itself. |
false |
working-directory |
Working directory to run xcodebuild in. |
— |
| Name | Description |
|---|---|
archive-path |
Resolved .xcarchive path, if any. |
export-path |
Resolved directory containing the exported IPA, if any. |
ipa-path |
First .ipa found inside export-path, if any. |
app-path |
First .app found inside export-path, if any (e.g. Developer ID). |
pkg-path |
First .pkg found inside export-path, if any (e.g. Mac App Store). |
result-bundle-path |
Resolved .xcresult path. Not set when action is export. |
log-path |
Resolved raw log path. |
- A macOS runner with Xcode installed (e.g.
runs-on: macos-14or newer). - The chosen
output-formattermust be onPATH.xcbeautifyis pre-installed on GitHub-hosted macOS runners; install it withbrew install xcbeautifyelsewhere, or setoutput-formatter: ''to disable.
Cause: an archive signed with a Mac App Store profile carries the com.apple.application-identifier and com.apple.developer.team-identifier entitlements, so any re-export of it, including Developer ID, needs a profile for that method. An app with no profile-only entitlements, archived without a profile, wouldn't need one. That's why the export often works locally and fails in CI.
Fix: create a MAC_APP_DIRECT (Developer ID) profile for the bundle ID with the Developer ID Application certificate, download it with download-provisioning-profiles, and map it under provisioningProfiles in ExportOptions-DeveloperID.plist.
yarn install
yarn build # bundles dist/index.js via @vercel/nccThe bundled dist/ directory is committed so the action can be consumed without a build step, matching the Apple-Actions convention.
package.json version is the version currently queued for the next release. Merge work to main, then ship with Actions → Release → Run workflow (default branch). CI tags vX.Y.Z, moves the major vX tag, creates a GitHub Release, and bumps package.json to the next minor so later changes queue for that version. Consumers on @vN pick up the new tip when the major tag moves.
For a major or patch instead of the queued minor, edit package.json on a PR first, merge, then run Release.
MIT