Fastlane is an open-source tool that automates the repetitive parts of shipping mobile apps: building, code signing, taking screenshots, uploading to TestFlight or Google Play, and managing metadata. It's Ruby-based, runs locally or in CI, and works with both iOS and Android.
The official docs are thorough but spread across dozens of pages. This tutorial condenses the setup into a practical walkthrough: install fastlane, configure it for your project, write lanes that build, test, and deploy, then plug in real-device testing to close the gap that fastlane can't cover on its own.
What fastlane does (and what it doesn't)
Fastlane is a build and deploy automation tool. It's made up of individual tools that each handle one step in the release pipeline:
produce creates new apps in App Store Connect and the Apple Developer Portal. cert manages code signing certificates. sigh handles provisioning profiles. gym (for iOS) and gradle (for Android) build the app. snapshot captures screenshots. deliver uploads builds and metadata to the App Store. supply does the same for Google Play. pilot manages TestFlight beta distribution.
What fastlane doesn't do: run functional tests on real devices. Fastlane can trigger test suites (via scan for iOS or gradle test for Android), but those tests run on simulators and emulators. Fastlane doesn't own the testing layer. It kicks off whatever tests you have and reports the results. If your tests don't cover real-device behavior, fastlane won't catch the gap.
Installation
Fastlane requires Ruby 2.7 or newer (3.3+ preferred). The cleanest installation uses Bundler to manage the dependency.
On macOS, you can also install via Homebrew (brew install fastlane), which bundles its own Ruby. Avoid installing to system Ruby with sudo gem install fastlane because file permission issues will surface later.
Then initialize fastlane in your project:
bundle exec fastlane init
Select option 4 (manual setup) when prompted. This creates a fastlane/ directory with two files: Appfile (app identifier and Apple ID) and Fastfile (your lanes).
Writing your first Fastfile: iOS
A lane is a sequence of actions. Here's a Fastfile with three lanes: one to run tests, one to push a beta to TestFlight, and one to deploy to the App Store.
What each action does:
scan runs your Xcode test suite (unit tests and UI tests) and reports results. increment_build_number bumps the build number so each upload is unique. match fetches code signing certificates and profiles from a private Git repo (this is fastlane's approach to team-wide code signing). gym builds the .ipa. pilot uploads to TestFlight. deliver uploads to the App Store with metadata and screenshots.
Run a lane from the terminal:
bundle exec fastlane beta
That single command increments the build, signs the app, builds it, and uploads to TestFlight. What used to take 20 minutes of manual clicking takes one terminal command.
Android Fastfile
The Android setup is similar but uses gradle instead of gym and supply instead of deliver.
For Android, supply requires a Google Play service account with API access. The official Android setup guide walks through creating the service account and linking it.
Where testing fits in the fastlane pipeline
Here's the typical flow:
- Fastlane builds the app (gym or gradle)
- Fastlane runs unit and UI tests (scan or gradle test)
- If tests pass, fastlane uploads to TestFlight or Play Store (pilot or supply)
Steps 1-3 all happen on your CI server (GitHub Actions, Jenkins, GitLab CI, Bitrise). Fastlane orchestrates the sequence. But here's the problem: scan runs tests in the iOS Simulator. gradle test runs tests on the JVM or an Android emulator. Neither runs on real devices.
That means your fastlane pipeline catches logic bugs and basic UI issues, but misses OEM-specific rendering (Samsung One UI font scaling, Xiaomi HyperOS security popups), real GPU performance, and device-specific layout breaks. These are the bugs that only show up on real hardware.
Plugging in real-device testing:
You can add a real-device testing step between "tests pass" and "upload to store" by calling the Drizz API from a custom fastlane lane. Drizz's REST API supports uploading APKs and triggering test plans from any CI pipeline.
desc "Run real-device tests via Drizz"
lane :real_device_tests do
# Upload the APK
sh("curl -X POST https://app.drizz.dev/api/tm/api/pub/apk/upload ...")
# Trigger the test plan
sh("curl -X POST https://app.drizz.dev/api/tm/api/pub/testplan/run ...")
end
Now the pipeline is: fastlane builds, runs unit/widget tests on simulator, uploads the APK to Drizz, runs plain-English tests on real devices using Vision AI, and only uploads to the store if both local tests and real-device tests pass. That closes the gap between "works on the emulator" and "works on the user's phone."
Common fastlane gotchas
Code signing with match. Match stores certificates and profiles in a private Git repo. It works well once set up, but first-time configuration requires revoking existing certificates and regenerating them. If your team uses manual code signing, the migration to match will temporarily break everyone's local builds. Do it during a planned maintenance window.
App Store Connect authentication. Fastlane supports three auth methods: App Store Connect API key (preferred), Apple ID with two-factor authentication (requires session cookie management), and Apple ID with app-specific password. The API key is the most reliable for CI because it doesn't require interactive 2FA.
Ruby version conflicts. If your macOS system Ruby conflicts with the version fastlane needs, builds will fail with cryptic dependency errors. Use rbenv or the Homebrew-bundled Ruby to isolate versions. Pin your Ruby version in .ruby-version and your fastlane version in the Gemfile.lock.
Android AAB vs APK. Google Play now requires Android App Bundles (.aab) instead of APKs for new apps. If your gradle task still outputs an APK, you'll need to switch to bundleRelease. Update the supply action's path accordingly.
FAQ
What is fastlane?
Fastlane is an open-source tool that automates mobile app builds, code signing, screenshots, metadata management, and deployment to the App Store and Google Play. It works for both iOS and Android.
Is fastlane free?
Yes. Fastlane is open-source under the MIT license. It was acquired by Google in 2017 and remains free. All tools run on your own machine or CI server, so credentials never leave your environment.
Can fastlane run tests?
Fastlane triggers test suites via scan (iOS) and gradle test (Android), but those tests run on simulators and emulators. For real-device testing, you need a separate tool like Drizz integrated into your fastlane pipeline.
Does fastlane work with Flutter and React Native?
Yes. For Flutter, use sh("flutter build apk") or the flutter community plugin. For React Native, use gradle (Android) and gym (iOS) the same way you would for a native project. The Fastfile doesn't change much.
How do I set up fastlane for a team?
Use match for code signing (stores certs in a shared Git repo), pin fastlane's version in a Gemfile.lock, and run bundle exec fastlane <lane> in CI. This ensures every team member and CI server uses the same fastlane version and signing config.
What CI services does fastlane work with?
GitHub Actions, Jenkins, GitLab CI, Bitrise, CircleCI, Travis CI, Azure DevOps, and any CI that can run Ruby commands. Most have official fastlane integration guides.
