A step-by-step guide to connecting your repository and configuring a first native iOS build on Codemagic, including workflow, Xcode version, and scheme selection.
Before you configure anything in Codemagic, make sure the fundamentals are in place. You need your iOS app in a Git repository hosted on GitHub, GitLab, or Bitbucket, since Codemagic builds from a connected repo. The project should build cleanly on your own Mac first: open the .xcodeproj or .xcworkspace in Xcode, select your scheme, and confirm it archives without errors locally. A build that fails on your machine will fail in the cloud, and debugging remotely is slower. Note your scheme name exactly, and make sure the scheme is marked as shared in Xcode (Product menu, then Scheme, then Manage Schemes, and tick Shared), because unshared schemes are not committed to the repository and Codemagic will not find them. Confirm which Xcode version you build with locally so you can match it in Codemagic. Finally, for anything beyond a plain unsigned build you will eventually need an Apple Developer Program membership, though your very first compile-only build can run without signing configured. Getting these basics right prevents most first-run frustration. It also helps to commit a clean, up-to-date lockfile — a Package.resolved for Swift Package Manager or a Podfile.lock for CocoaPods — so the cloud resolves the exact dependency versions you tested locally rather than drifting to newer ones.
Sign up for Codemagic and choose to authenticate with the Git provider that hosts your project. When you authorize the integration, grant access to the specific repository or organization you want to build; you can usually scope this narrowly rather than granting blanket access to every repo you own. Once connected, Codemagic lists your available repositories. Select the one containing your iOS app and add it as an application. Codemagic then inspects the repository to detect the project type. For a native iOS app it looks for Xcode project or workspace files and identifies it as an iOS or native project rather than Flutter or React Native. If your repository contains multiple apps or a monorepo layout, be prepared to point Codemagic at the correct subdirectory and project file. At this stage you have not built anything yet; you have simply told Codemagic where your code lives and given it permission to check out commits. Confirming the correct repository and default branch now saves confusion later when builds trigger on the wrong branch. If your provider is self-hosted or behind SSO, you may need an administrator to approve the integration, so factor that into your setup time.
Codemagic offers two ways to define a build: the visual workflow editor in the UI, and a codemagic.yaml file committed to your repository. For a first build and for learning, the UI editor is approachable — it presents dropdowns for the Xcode version, macOS machine, scheme, and build steps. However, for anything you intend to maintain over time, prefer codemagic.yaml. Committing the file to your repo means your build definition is version-controlled, reviewable in pull requests, reproducible across branches, and portable if you ever migrate. The YAML defines named workflows, each with an environment section (Xcode and CocoaPods versions, environment variables), a scripts section listing the shell commands to run, and optional sections for artifacts and publishing. A minimal iOS workflow specifies the macOS instance type, the Xcode version, a build step that invokes xcodebuild or the Codemagic build helpers, and a list of artifacts to collect. You can start in the UI to understand the options, then switch to YAML once the pipeline stabilizes. Both live in the same account; choose one as the source of truth to avoid confusion. Note that once a codemagic.yaml file is present in your repository, Codemagic uses it and the UI editor settings no longer drive those builds, which is exactly the clean cutover you want.
The Xcode version your build uses is one of the most consequential settings, because it must be compatible with your project's Swift language version, deployment target, and any SDK features you rely on. Codemagic maintains a set of macOS images each preloaded with specific Xcode versions. Choose a version that matches, or is close to, what you use locally. Pinning an explicit version rather than a floating 'latest' alias is strongly recommended, because 'latest' can change under you when Codemagic updates its images, potentially breaking a previously green build without any change to your code. In codemagic.yaml this is set in the environment section with an xcode key. You also choose a machine type or instance; more powerful macOS machines compile faster but consume build minutes at a higher rate. For a first build, a standard machine is fine. Match the CocoaPods version too if your project uses it, since a mismatched Pods toolchain can cause resolution failures. Being explicit about versions is the single biggest thing you can do to keep cloud builds reproducible. It is worth recording your chosen Xcode, Swift, and CocoaPods versions in a comment at the top of the YAML so the next person who edits the pipeline understands why those exact values were selected.
The heart of the workflow is the build step that compiles your app. Codemagic needs to know which scheme to build and, if you use a workspace, the workspace path. In the UI you select the scheme from a dropdown that Codemagic populates by inspecting your project; if your scheme is missing, it is almost always because it is not shared in Xcode. In YAML you either call Codemagic's build helper or invoke xcodebuild directly, passing the workspace or project, the scheme, and the configuration (typically Release for distribution or Debug for a quick test build). If you use Swift Package Manager, dependency resolution happens automatically during the build; if you use CocoaPods, add a script step to run pod install before building. For this first pass, aim for an unsigned build or a build that only compiles and runs tests, so you can verify the toolchain works before layering in code signing. Getting a clean compile and a produced build log confirms your environment, scheme, and Xcode version are all aligned correctly. If your project reads secrets or API endpoints from environment variables at build time, define those in Codemagic's environment variable settings now, marking anything sensitive as secure so it is encrypted and masked in logs.
Decide when builds should run. Codemagic supports triggering on push to specific branches, on pull requests, on tag creation, and manually on demand. For an initial setup, a manual trigger is simplest: you press Start new build, pick the branch, and watch it run. Once you trust the pipeline, add automatic triggers — for example, build every push to your main branch, or build when a version tag is pushed for release candidates. Branch and tag patterns let you avoid burning build minutes on every trivial commit to feature branches. Configure triggers in the UI's build settings or in the triggering section of codemagic.yaml. When you launch the build, Codemagic queues it, waits for an available macOS machine, checks out your commit, and runs each step in order. Watch the live log stream; it shows dependency resolution, compilation, and any warnings or errors. The first successful run is the milestone that confirms your repository connection, Xcode version, and scheme are all working together before you add signing and publishing. For pull request triggers you will also need to grant Codemagic webhook access on your Git provider, which the integration usually configures for you but is worth verifying if PR builds do not fire.
After the build completes, Codemagic surfaces the artifacts it collected — build logs, test results, and, once signing is configured, the .ipa or .xcarchive. In codemagic.yaml you declare which files to keep in the artifacts section using path patterns; for an unsigned first build you might simply collect the build log and any test output. Review the logs carefully even on a green build, because warnings there often foreshadow problems that will surface once you add signing. Verify that the scheme built was the one you intended and that the Xcode version reported in the log matches what you configured. If tests ran, confirm they actually executed rather than being silently skipped. Download the artifacts to inspect them. This verification step matters because a build that 'succeeds' but produces the wrong configuration or skips your tests gives false confidence. Once you have a reliable, reproducible compile-and-test workflow, you have a solid foundation to add App Store Connect API key signing and TestFlight publishing in the next stages of your pipeline. Consider adding email or Slack notifications on build completion at this point too, so the team learns about failures immediately rather than discovering a broken main branch hours later.
Almost always because the scheme is not marked as shared in Xcode. Open Product, Scheme, Manage Schemes, tick the Shared checkbox for your scheme, and commit the resulting file under xcshareddata. Codemagic can only build schemes that are committed to the repository.
Use the UI to learn the options quickly, but prefer codemagic.yaml for anything you maintain long-term. Committing the YAML makes your build version-controlled, reviewable in pull requests, and reproducible across branches. Pick one as your source of truth to avoid conflicting definitions.
Pick a version matching, or close to, what you build with locally, and pin it explicitly rather than using a floating 'latest' alias. Explicit pinning prevents Codemagic image updates from silently breaking a previously working build.
Yes. You can run a compile-only or test-only build without signing configured to verify your toolchain, scheme, and Xcode version work. Signing is only required once you want to produce a distributable .ipa for TestFlight or the App Store.
If your project uses CocoaPods, add a script step running pod install before the build, and match the CocoaPods version to what you use locally. Swift Package Manager dependencies resolve automatically during the build without an extra step.