A step-by-step guide to installing Fastlane, initializing it inside an Xcode project, and creating your first working lane for a native iOS app.
This guide assumes you already have a native iOS app that builds and runs in Xcode. Fastlane automates Xcode's steps; it does not create the app for you, so you need a working Xcode project or workspace first.
You also need macOS with Xcode installed, along with the Xcode command line tools. Confirm the tools are present by running xcode-select --install if you have never installed them.
Finally, have your Apple Developer Program account details ready. Most useful lanes eventually touch signing or App Store Connect, both of which require Apple credentials.
If your project came from a React Native, Expo, or web-based builder, note that only the native iOS portion is what Fastlane operates on. You still need that native Xcode project present before any of the steps below apply.
Fastlane is a Ruby gem, and there are a few installation paths. The most common approaches are installing via Homebrew with brew install fastlane, or installing as a gem with gem install fastlane.
For team projects, the recommended path is to manage Fastlane through Bundler. Create a Gemfile in your project root containing a line for the fastlane gem, then run bundle install.
This pins a known version so every developer and your CI machine use the same Fastlane. Version consistency prevents a whole category of confusing failures later.
After installing, run fastlane --version to confirm it is available. If you used Bundler, prefix commands with bundle exec, as in bundle exec fastlane --version.
Whichever method you pick, avoid mixing them within a single project. A globally installed Fastlane and a Bundler-managed one can resolve to different versions, and that ambiguity is exactly what pinning is meant to remove.
Navigate to your project's root directory in the terminal, the folder that contains your .xcodeproj or .xcworkspace. Run fastlane init (or bundle exec fastlane init if using Bundler).
Fastlane will ask what you want to automate and may prompt for your Apple ID and app identifier. It then creates a fastlane directory containing two key files: the Fastfile, where your lanes live, and the Appfile, which stores your app identifier and Apple account details.
Commit these files to version control. They are the heart of your automation and should be shared across the team.
Be careful not to commit secrets. Keep passwords and API keys out of these files and in environment variables or a secrets manager instead.
If fastlane init asks which platform to configure, choose the iOS path. It will inspect your project, detect the app identifier where it can, and scaffold a starting Fastfile you can immediately refine.
The Fastfile is Ruby. Inside it you define lanes, which are named sequences of actions. A lane might look like a block that begins with lane :beta do and ends with end, containing the steps you want to run.
Each step inside a lane is an action, such as build_app (gym) or upload_to_testflight (pilot). Actions accept parameters that configure their behavior.
Because the Fastfile is real Ruby, you can use variables, conditionals, and loops. This flexibility is powerful but easy to overuse.
Start simple. A readable Fastfile with a few clear lanes beats a clever one nobody can maintain, and you can always refactor toward shared helpers once the workflow stabilizes.
A useful convention is to give each lane a single clear purpose, such as test, beta, or release. When lanes map cleanly to intentions, the command you run reads like the outcome you want, which keeps the whole team on the same page.
Start with something low-risk that does not touch the App Store. A good first lane runs your tests. Define a lane named test that calls the run_tests action (scan), pointing it at your scheme.
Run it with fastlane test. If your scheme name and project are correctly detected, Fastlane will compile and run your test suite, then print a formatted summary.
This confirms your basic setup works before you add signing or uploads. Getting a green test run through Fastlane is a meaningful milestone.
Once tests pass through Fastlane, add a build lane that calls build_app with your scheme. This produces a signed .ipa and validates that your build configuration is understood by Fastlane.
Signing is where iOS automation gets real. For team projects, set up Match to manage certificates and provisioning profiles in an encrypted Git repository. Run fastlane match init to create a Matchfile, then generate assets with commands like fastlane match appstore.
For a quick solo setup, you can rely on Xcode's automatic signing and pass the appropriate export options to build_app, but Match is strongly recommended once more than one machine is involved.
Whichever path you choose, verify that a build lane produces a correctly signed .ipa before moving on to uploads.
Signing errors are the most common early stumbling block, so resolve them here rather than mid-release. A signing problem isolated to your build lane is far easier to debug than one buried inside a full release run.
With building and signing working, add a TestFlight lane. It typically bumps the build number, calls build_app, then calls upload_to_testflight.
For authentication, prefer an App Store Connect API key over an Apple ID and password, since API keys work cleanly on CI and avoid two-factor prompts.
Run this lane to push a build to TestFlight. Once it succeeds, you have a complete local pipeline: test, build, sign, and distribute to testers with one command.
Keep credentials out of the Fastfile. Reference environment variables so the same lane runs locally and on CI without exposing secrets in version control.
The whole point of Fastlane is unattended runs. On CI, use non-interactive authentication everywhere: an App Store Connect API key for uploads and Match with a read-only key for signing. Set these values as encrypted CI secrets.
Make sure your CI job uses the same Fastlane version as local development by committing your Gemfile and Gemfile.lock and running through bundle exec. Version drift between local and CI is a frequent source of confusing failures.
With that in place, your CI can run a single lane on each push or tag. Start by triggering the test lane on pull requests and the beta lane on merges to your release branch.
From there you can expand incrementally, adding App Store submission lanes and screenshot automation once the core beta pipeline has proven reliable across several runs.
Basic usage requires almost none, since the Fastfile reads like a simple script. But because the Fastfile is real Ruby, deeper customization benefits from Ruby familiarity.
For team and CI projects, use Bundler with a Gemfile so everyone runs the same version. Global installation is fine for quick local experiments.
It creates a fastlane directory containing a Fastfile, where you define lanes, and an Appfile, which holds your app identifier and Apple account details. Both should be committed, minus any secrets.
No. You need an existing native Xcode project. Fastlane automates building, signing, and releasing that project, not creating it.