A step-by-step guide to adding an iOS app to Bitrise and configuring your first workflow — choosing a macOS stack and Xcode version, picking your scheme, and running a build through the Workflow Editor.
Before adding an app to Bitrise, gather a few things so the setup runs smoothly. You need a Bitrise account, which you can create for free, and access to the Git repository that contains your iOS project — hosted on GitHub, GitLab, Bitbucket, or reachable through a generic Git URL. Bitrise will need read access to clone the repo, typically granted by connecting your Git provider account or by adding an SSH key that Bitrise generates. On the Apple side, you should have an Apple Developer Program membership if you eventually plan to sign and distribute, although the very first plain build-and-test workflow can often run without signing configured. It helps to know your project's scheme name in advance; open the project in Xcode, check the scheme selector in the toolbar, and confirm the scheme is marked as Shared under Product, Scheme, Manage Schemes, because Bitrise can only build schemes that are shared and committed to the repository. Finally, make sure your project actually builds locally in Xcode first, since Bitrise cannot fix a project that is already broken on your own machine.
From the Bitrise dashboard, choose to add a new app and select the workspace it should belong to. You then pick the Git provider and the specific repository. If this is the first time connecting that provider, Bitrise will walk you through authorizing access; if you prefer not to link your account, you can add the repository by URL and register the SSH key Bitrise provides with your Git host so it can clone privately. Next you select the branch Bitrise should scan to detect the project — usually your main or develop branch. Bitrise then runs an automatic project scanner that inspects the repository, identifies it as an iOS project, and locates the Xcode workspace or project file along with the available shared schemes. This scanning step is where a missing shared scheme most often causes trouble, so if Bitrise cannot find your scheme, return to Xcode, share it, commit the .xcscheme file under xcshareddata, and push before rescanning. Once detection succeeds, Bitrise proposes a starter configuration you can accept and refine.
A critical decision during setup is which build stack to run on. In Bitrise, a stack is a specific macOS machine image bundled with a particular Xcode version and its associated toolchain. Choosing the right stack matters because your project's Swift version, deployment target, and any SDK features must be compatible with the Xcode on that stack. As a rule, match the stack's Xcode version to the version your team uses locally, or to the minimum version App Store Connect currently requires for submissions. You configure the stack per app and can override it per workflow, which is useful when you want, for example, a bleeding-edge Xcode for experimental branches while keeping releases on a proven version. When Apple ships a new Xcode, Bitrise publishes new stacks, and older stacks are eventually deprecated, so record which stack you chose and revisit it periodically. Selecting a stack whose Xcode is too old for your project causes compile failures, while one too new can surface Swift language-mode or SDK changes, so pin deliberately rather than defaulting blindly to the newest option offered during onboarding.
After onboarding, Bitrise generates a starter workflow, commonly a primary workflow, made up of a sequence of Steps. A typical iOS starter includes an Activate SSH key Step, a Git Clone Repository Step, a caching Step to speed up dependency restoration, a Step to install dependencies such as CocoaPods or Swift Package Manager resolution, an Xcode Test for iOS Step, and a deploy Step that stores build artifacts. Open the Workflow Editor to see this sequence laid out visually. Each Step exposes inputs you can configure through a form — for the test Step, for instance, you set the project or workspace path, the scheme, and the simulator device and OS to run tests against. Take time to read through the default Steps rather than immediately adding new ones, because the generated pipeline already covers the common path of clone, build, and test. Every edit you make here is written to the app's bitrise.yml, which you can view by switching to the YAML tab, giving you a text representation of exactly what the visual editor produced.
The single most important configuration for a reliable iOS build is telling each Step exactly which project and scheme to use. In the Workflow Editor, open your Xcode Test or Xcode Archive Step and set the Project path input to your .xcworkspace if you use CocoaPods or a workspace, or your .xcodeproj otherwise. Then set the Scheme input to the exact, case-sensitive name of your shared scheme. Many teams centralize these values using Bitrise Environment Variables so that multiple Steps reference the same BITRISE_PROJECT_PATH and BITRISE_SCHEME rather than repeating literals. You can define app-level environment variables in the app settings and workflow-level ones in the editor. If your project requires dependency resolution, confirm the correct Step is present and configured: for CocoaPods you want the Run CocoaPods install Step before building, and for Swift Package Manager, xcodebuild resolves packages during the build as long as network access and package resolution succeed. Getting these paths and the scheme exactly right eliminates the most common cause of first-build failures, which is Bitrise building the wrong target or none at all.
With the workflow configured, trigger a build. You can start one manually from the dashboard by choosing the branch and the workflow to run, or you can push a commit if you have already set up trigger rules. Bitrise queues the build, provisions a fresh macOS machine on your chosen stack, and streams live logs as each Step executes. Watch the log output closely: the Git Clone Step confirms the repository and commit, the dependency Step shows CocoaPods or package resolution, and the Xcode Step prints the underlying xcodebuild invocation, which is invaluable for debugging because you can reproduce that exact command locally. If the build succeeds, you will see green checkmarks down the Step list and any artifacts, such as test results or a build log, available on the build's Artifacts tab. If it fails, the failing Step is highlighted, and the log around the failure almost always names the cause — a missing scheme, an unresolved dependency, or a signing error. Because each build runs on a clean machine, a green build here is a strong signal that your project is reproducible beyond one developer's laptop.
Once your first workflow builds reliably, wire it into your team's Git activity using Bitrise's trigger map. In the Triggers section you define rules such as: run the test workflow on every pull request, run it on pushes to develop, and run a separate deploy workflow on pushes to a release branch or on tags. This turns Bitrise from a manual button into an automated safety net that validates every change before it merges. From here, natural next steps are configuring code signing so you can produce a distributable .ipa, adding a Deploy to App Store Connect Step to push builds to TestFlight, and introducing caching tuning to shorten build times and reduce credit consumption. Keep your bitrise.yml under version control by committing it to the repository, which lets you review CI changes in pull requests and roll back if a workflow edit breaks the pipeline. Document which stack and Xcode version you standardized on so teammates understand the environment, and revisit that choice whenever Apple releases a new Xcode that your submission targets require.
Bitrise can only build schemes that are shared and committed to your repository. In Xcode, open Product, Scheme, Manage Schemes, tick the Shared checkbox for your scheme, then commit the generated .xcscheme file under xcshareddata and push. Rescan the project in Bitrise afterward. An unshared scheme is the most common reason the automatic scanner fails to detect a buildable target.
Match the stack's Xcode version to what your team uses locally and to the minimum version App Store Connect currently requires for submissions. Selecting an Xcode that is too old causes compile errors, while one that is too new can surface Swift language-mode or SDK changes. You can set the stack per app and override it per workflow, so pin it deliberately rather than always taking the newest option.
A basic build-and-test workflow that only compiles and runs unit or UI tests on the simulator can often run without full signing configured. However, to produce a signed .ipa, run on real devices, or distribute to TestFlight or the App Store, you need an active Apple Developer Program membership and valid signing assets. Plan to add that membership before your first distribution workflow.
Yes. Every change in the Workflow Editor is written to a bitrise.yml file, and you can switch to the YAML tab to edit it directly. Committing bitrise.yml to your repository lets you version-control CI configuration, review it in pull requests, and roll back bad changes. The visual editor and the YAML are two views of the same underlying configuration.
Use Bitrise's trigger map, found in the Triggers section of your app. There you create rules that map Git events — pull requests, pushes to specific branches, or tags — to specific workflows. A common setup runs your test workflow on every pull request and a separate deploy workflow on release branches or tags, so every change is validated before it merges.