{"id":13995980,"url":"https://github.com/mxcl/xcodebuild","last_synced_at":"2025-10-05T06:37:26.873Z","repository":{"id":37595688,"uuid":"373928135","full_name":"mxcl/xcodebuild","owner":"mxcl","description":"A continuously resilient `xcodebuild` “GitHub Action”. Also it’s the best.","archived":false,"fork":false,"pushed_at":"2024-09-16T14:59:44.000Z","size":1435,"stargazers_count":300,"open_issues_count":4,"forks_count":25,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-14T13:04:30.588Z","etag":null,"topics":["github-actions","macos","xcode","xcodebuild"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxcl.png","metadata":{"funding":{"github":"mxcl","patreon":"mxcl"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-04T18:25:51.000Z","updated_at":"2024-10-01T07:30:14.000Z","dependencies_parsed_at":"2024-10-05T19:19:04.263Z","dependency_job_id":null,"html_url":"https://github.com/mxcl/xcodebuild","commit_stats":{"total_commits":123,"total_committers":5,"mean_commits":24.6,"dds":0.5203252032520325,"last_synced_commit":"0fc501a3b84ff7a08dc95d36faf83b6b5bd74245"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2Fxcodebuild","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2Fxcodebuild/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2Fxcodebuild/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxcl%2Fxcodebuild/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxcl","download_url":"https://codeload.github.com/mxcl/xcodebuild/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980843,"owners_count":21027808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-actions","macos","xcode","xcodebuild"],"created_at":"2024-08-09T14:03:42.824Z","updated_at":"2025-10-05T06:37:26.775Z","avatar_url":"https://github.com/mxcl.png","language":"TypeScript","readme":"# mxcl/xcodebuild\n\nMake your software #continuously-resilient as well as continuously integrated.\n\nThis action will continue to work forever, no more CI breakage because Xcode\nis updated.\n\nThe action will build both Xcode projects and Swift packages.\n\n## [Sponsor @mxcl](https://github.com/sponsors/mxcl)\n\nI can only afford to maintain projects I need or that are sponsored. Thanks.\n\n## Usage\n\n\u003e For complete input/output documentation, see [action.yml](action.yml).\n\n```yaml\njobs:\n  build:\n    runs-on: macos-latest\n    steps:\n      - uses: mxcl/xcodebuild@v3\n      # ^^ this is the simplest use, runs tests for whatever platform `xcodebuild` picks\n```\n\n```yaml\njobs:\n  build:\n    runs-on: macos-latest\n    strategy:\n      matrix:\n        platform:\n          - macOS\n          - watchOS\n          - tvOS\n          - iOS\n          - mac-catalyst\n          - visionOS\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          platform: ${{ matrix.platform }}\n```\n\n```yaml\njobs:\n  build:\n    strategy:\n      matrix:\n        platform:\n          - macOS\n          - watchOS\n          - tvOS\n          - iOS\n        xcode:\n          - ^10 # a semantic version range †\n          - ^11\n          - ^12\n    runs-on: macos-10.15\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          xcode: ${{ matrix.xcode }}\n          platform: ${{ matrix.platform }}\n          action: build # default = `test`\n          code-coverage: true # default = `false`\n          warnings-as-errors: true # default = `false`\n          configuration: release # no default, ie. `xcodebuild` decides itself\n```\n\n\u003e † check out https://devhints.io/semver for valid ranges\n\n```yaml\njobs:\n  build:\n    strategy:\n      matrix:\n        platform:\n          - iOS\n        platform-version:\n          - ^15\n          - ^16\n          - ^17\n    runs-on: macos-latest\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          platform-version: ${{ matrix.platform-version }}\n          platform: ${{ matrix.platform }}\n```\n\n```yaml\njobs:\n  build:\n    runs-on: macos-11\n    strategy:\n      matrix:\n        swift:\n          - ~5.3\n          - ~5.4\n          - ^6\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          swift: ${{ matrix.swift }}\n          # ^^ mxcl/xcodebuild selects the newest Xcode that provides the requested Swift\n          # obviously don’t specify an Xcode range *as well*\n        continue-on-error: ${{ matrix.swift == '^6' }}\n        # ^^ pre-emptively try to build against unreleased versions\n```\n\nIf you need to test against Swift versions that cross macOS images then you will\nwant something like this:\n\n```yaml\njobs:\n  build:\n    runs-on: ${{ matrix.os }}\n    strategy:\n      matrix:\n        swift:\n          - ~5.0 # Xcode 10.3\n          - ~5.1 # Xcode 11.3.1\n          - ~5.2 # Xcode 11.7\n          - ~5.3 # Xcode 12.4\n        os:\n          - macos-10.15\n        include:\n          - swift: ~5.4 # Xcode 12.5.1\n            os: macos-11\n          - swift: ~5.5\n            os: macos-11 # Xcode 13\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          swift: ${{ matrix.swift }}\n```\n\nYou _can_ use this action to just select Xcode and perform no action:\n\n```yaml\njobs:\n  build:\n    runs-on: ${{ matrix.os }}\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          action: none\n      - run: … # do your own thing\n```\n\n## Specifying `workspace`\n\nYou can specify `workspace`.\n\nIf you are using CocoaPods you will likely need to specify the workspace, it is NOT automatically\ndeciphered for you.\n\n## Specifying `scheme`\n\nYou can specify `scheme`.\nIf you don’t we try to figure it out for you; this sometimes fails.\n\nIdeally if there is only one scheme you wouldn’t need to specify it,\nif you think we could have figured it out but didn’t please open a ticket.\n\n## Available Xcodes\n\nGitHub’s images have a **limited selection** of Xcodes.\n\n- GitHub list what is available for the current [10.15][gha-xcode-list-catalina]\n  and [11][gha-xcode-list-big-sur] images.\n- We run a scheduled workflow to determine what is available [here][automated-list].\n\nTo install other versions first use [sinoru/actions-setup-xcode], then\n`mxcl/xcodebuild` _will find that Xcode_ if you specify an appropriate value for\nthe `xcode` input.\n\n## Logs\n\nWe automatically upload the build logs as artifacts on failure.\n\nThe resulting artifact is an `.xcresult` “bundle” and once downloaded can be\nopened in Xcode:\n\n![img]\n\nYou’ll even get your coverage report!\n\n\u003e Note this feature requires Xcode \u003e= 11\n\n## `.swift-version` File\n\nIf your repo has a `.swift-version` file and neither `swift` nor `xcode` is\nspecified it will be read and that Swift version resolved.\n\nIf `working-directory` is set, the `.swift-version` file is read from this\ndirectory.\n\nThis behavior cannot currently be disabled, PR welcome.\n\n## Code Signing\n\n\u003e This feature requires macOS.\n\nCode signing can be enabled with either an App Store Connect API key, or with a\ncertificate.\n\n### Using an App Store Connect API Key\n\n\u003e This feature requires Xcode 13 or later.\n\n[Create][create-api-key-instructions] an API key on\n[App Store Connect][create-api-key]. Download your key and Base64-encode it:\n\n```bash\nbase64 AuthKey_9XXXX9XXXX.p8\n```\n\nCreate [GitHub Secrets][secrets] for your base64-encoded key, the key ID, and\nthe key's issuer ID. The IDs are displayed on App Store Connect.\n\n```yaml\njobs:\n  build:\n    runs-on: macos-latest\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          authentication-key-base64: ${{ secrets.APP_STORE_CONNECT_KEY_BASE64 }}\n          authentication-key-id: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}\n          authentication-key-issuer-id: ${{ secrets.APP_STORE_CONNECT_KEY_ISSER_ID }}\n```\n\nCertificates and provisioning profiles will be created automatically using the\nApp Store Connect API. Certificates will appear in your\n[list of certificates](cert-list) as `Created via API`.\n\nDevices will be registered automatically. GitHub-hosted runners will appear in\nin your [list of devices](device-list) as `mac-NUMBER.local`.\n\n\u003e :warning: This may cause undesired behavior when using GitHub-hosted runners.\n\u003e For best results, use App Store Connect API keys only on self-hosted runners.\n\nFor more information on this method of code signing, please review the\n[\"Distribute apps in Xcode with cloud signing\"][cloud-signing] talk from WWDC21.\n\n### Using a Specific Certificate\n\nIf you are not able to use an App Store Connect API key, and you have a specific\ncode signing certificate you'd like to use, it can be installed to the macOS\nKeychain. It is automatically removed from the Keychain in a post action.\n\n```yaml\njobs:\n  build:\n    runs-on: macos-latest\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          code-sign-certificate: ${{ secrets.CERTIFICATE_BASE64 }}\n          code-sign-certificate-passphrase: ${{ secrets.CERTIFICATE_PASSPHRASE}}\n```\n\nTo export your certificate from Xcode and Base64 encode it, follow\n[these instructions][export]. Store any secrets, including certificates and\npassphrases, in GitHub as [Encrypted Secrets][secrets].\n\n### Specifying an Identity\n\nYou may specify a `code-sign-identity` to override any `CODE_SIGN_IDENTITY`\nspecified by your project.\n\n### Disabling Code Signing\n\nTo disable code signing, you can specify `code-sign-identity: '-'`.\n\n### Provisioning Profiles\n\nIf you are not able to use an App Store Connect API key, and you have specific\nprovisioning profiles you'd like to use, you can specify profiles for Mac\n`provisioning-profiles-base64`, or for iOS or other devices using\n`mobile-provisioning-profiles-base64`.\n\nTo export your provisioning profiles from Xcode and Base64 encode these, follow\n[these instructions][export]. Store any secrets, including provisioning\nprofiles, in GitHub as [Encrypted Secrets][secrets].\n\n```yaml\njobs:\n  build:\n    runs-on: macos-latest\n    steps:\n      - uses: mxcl/xcodebuild@v3\n        with:\n          mobile-provisioning-profiles-base64: |\n            ${{ secrets.IPHONE_PROVISIONING_PROFILE_BASE64 }}\n            ${{ secrets.IPAD_PROVISIONING_PROFILE_BASE64 }}\n          provisioning-profiles-base64: |\n            ${{ secrets.MAC_PROVISIONING_PROFILE_BASE64 }}\n```\n\n## Caveats\n\n- The selected Xcode remains the default Xcode for the image for the duration of\n  your job.\n\n## Neat Stuff\n\n- We’re smart based on the selected Xcode version, for example we know watchOS\n  cannot be tested prior to 12.5 and run xcodebuild with `build` instead\n- We figure out the the simulator destination for you automatically. Stop\n  specifying fragile strings like `platform=iphonesimulator,os=14.5,name=iPhone 12`\n  that will break when Xcode updates next week.\n- You probably don’t need to specify project or scheme since we aren’t tedious\n  if possible\n- `warnings-as-errors` is only applied to normal targets: not your tests\n\n## Continuous Resilience\n\n- Use `macos-latest` and trust this action to always work\n  - This because GitHub deprecate old environments, so if you want your CI to\n    continue to work in 5 years you need to use `latest`\n  - This makes specifying specific xcode versions problematic however, we\n    haven’t got a good story for this yet.\n- Set up a scheduled job for your CI for at least once a week\n  - This way you’ll be notified if a new version of something (like Xcode)\n    causes breakage in your builds\n\n## Linux\n\nIf your project is a Swift Package (which it would have to be to build on Linux)\nthen by far the best and quickest way to build on Linux is by using the official\nSwift docker containers:\n\n```yaml\njobs:\n  build:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        swift:\n          - '5.0' # string or you’ll get 5.5!\n          - 5.1\n    container:\n      image: swift:${{ matrix.swift }}\n    steps:\n      - run: swift test\n```\n\nThis action does not support Linux.\n\n## Windows\n\nUse: https://github.com/marketplace/actions/swift-for-windows-action\n\nThis action does not support Windows.\n\n## Contributing\n\n1. Run `npm install`\n1. Edit the various `.ts` files\n1. Run `npm run prepare`\n1. Correct any lint issues with `npm run format` or in your editor\n1. If there are lint failures, try\n1. Create a [Pull Request](https://github.com/mxcl/xcodebuild/compare)\n\n[automated-list]: https://flatgithub.com/mxcl/.github/?filename=versions.json\n[cloud-signing]: https://developer.apple.com/videos/play/wwdc2021/10204/\n[create-api-key]: https://appstoreconnect.apple.com/access/api\n[create-api-key-instructions]: https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api\n[cert-list]: https://developer.apple.com/account/resources/certificates/list\n[device-list]: https://developer.apple.com/account/resources/devices/list\n[gha-xcode-list-catalina]: https://github.com/actions/virtual-environments/blob/main/images/macos/macos-10.15-Readme.md#xcode\n[gha-xcode-list-big-sur]: https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11-Readme.md#xcode\n[sinoru/actions-setup-xcode]: https://github.com/sinoru/actions-setup-xcode\n[img]: https://raw.githubusercontent.com/mxcl/xcodebuild/gh-pages/XCResult.png\n[secrets]: https://docs.github.com/en/actions/reference/encrypted-secrets\n[export]: https://docs.github.com/en/actions/guides/installing-an-apple-certificate-on-macos-runners-for-xcode-development#creating-secrets-for-your-certificate-and-provisioning-profile\n\n![Analytics](https://repobeats.axiom.co/api/embed/d18c74fbcc8431bca3d0dd76cc3131c32df24dce.svg 'Repobeats analytics image')\n","funding_links":["https://github.com/sponsors/mxcl","https://patreon.com/mxcl"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxcl%2Fxcodebuild","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxcl%2Fxcodebuild","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxcl%2Fxcodebuild/lists"}