A Tourist’s Guide to fastlane

Inspired by A Tourist’s Guide to the LLVM Source Code, which I discovered through a Tweet by Rob Story,

Which I saw as a retweet of a retweet…

I thought, “I could write a similar guide for fastlane.”

For folks who aren’t familiar with it, fastlane is a open-source command-line tool written in Ruby. It automates beta and release deployment for your iOS or Android apps, including build, code signing, automatic screenshot capture, and distribution of your app binaries.

One of the things about fastlane that’s toughest for newcomers to navigate is its considerable collection of proper nouns. Most of these are the names of the many individual projects that originally existed as stand-alone tools. Over time, fastlane has evolved to put less emphasis on each individual tool, and more emphasis on fastlane as the provider of these many capabilities. Still, the names persist, and if nothing else, I hope to provide a consolidated glossary for them here.

fastlane moves quickly. Since I started helping maintain it in November 2015, fastlane has been restructured and reorganized twice, changing where its code lives, how it’s built, and how it’s deployed. So, before I describe how things currently are, let’s review how we got here.

Organizations and repositories

Prior to March 2016, fastlane’s tools each had their own repository within the fastlane organization on GitHub. Since bringing all of those projects together into the “monorepo”, all of the source code for fastlane now lives in a single fastlane project repository. This has allowed us to consolidate pull requests and issues into one place, making it easier for users to reach us, and easier for maintainers to manage. If you’re curious to dig through some history, all of the original tool repositories still exist in the fastlane-old organization.

In December 2016, we made fastlane into a “monogem”, which we released as fastlane 2.0. This change carried the “monorepo” work one step further by allowing all of fastlane’s tools to be built and deployed as a single Ruby gem. This greatly simplifies the fastlane release process by removing the need to individually deploy (and Tweet about) each sub-project.

Present structure

The current fastlane organization still contains a number of repositories, the most notable of which are:

• docs holds the documentation site that we host at docs.fastlane.tools
• examples stores a collection of example fastlane configurations provided by community. If you want to see some real-world, production-tested, fastlane setups, take a look through here
• fastlane is the main code repository for fastlane. We’ll dive deeper into this, next
• packaged-fastlane contains the code that builds the new installer artifact for fastlane. That package brings fastlane together with a self-contained Ruby environment to make installation simple and easy

The fastlane repository

Starting from the root, the first level of the fastlane repository serves mostly to organize its many tools into sub-projects, with each providing a particular capability. These are the main proper nouns of fastlane, and they are:

• cert/ creates and maintains iOS code signing certificates. Rather than using cert directly, you should try to use match, first
• credentials_manager/ is used by many of the tools to interact with the Mac keychain for securely storing and retrieving user credentials
• deliver/ uploads screenshots, metadata, and your iOS app binary to the App Store
• fastlane/ defines how to execute Fastfiles and their lanes. It contains the code for all of the actions that ship with fastlane, as well as defining the plugins system that allows you to define your own actions. Did you know that fastlane is built and deployed using fastlane? The Fastfile that defines all of that logic lives here, too
• fastlane_core/ contains shared code for things like logging, UI output, update checking, reporting crashes, and recording usage. Other important Apple-specific utility classes are also kept here, including a class to represent an Xcode project, and a class to wrap interactions with the iTMS Transporter
• frameit/ quickly puts your screenshots into the right Apple device frames
• gym/ takes care of the heavy lifting to make it easy to generate signed iOS or Mac app binaries
• match/ easily syncs your iOS certificates and profiles across your team using Git. Uses cert and sigh behind the scenes
• pem/ generates and renews your Apple push notification certificates
• pilot/ manages testers and delivers builds to Apple’s TestFlight
• produce/ creates new iOS apps on iTunes Connect and the Apple Developer Portal
• scan/ is the easiest way to run tests for your iOS and Mac apps
• screengrab/ automates taking localized screenshots of your Android apps on every device
• sigh/ creates, renews, downloads, and repairs iOS provisioning profiles. Rather than using sigh directly, you should try to use match, first
• snapshot/ automates taking localized screenshots of your iOS apps on every device
• spaceship/ is a library for accessing the Apple Developer Portal and iTunes Connect web services. Any of the other tools that talk to these services do so through spaceship
• supply/ uploads screenshots, metadata, and your Android app binary to the Play Store

A fastlane tool project

Each of the above fastlane tool sub-projects share some structural similarities. The following landmarks can generally be found in each:

• assets/ contains any static assets, like images, used in the sub-project’s README
• example/ tends to collect a “code zoo” of unusual or interesting fixture data, or projects that can be used to test the tool
• lib/ is where all the code lives. We’ll drill a little deeper here, next
• spec/ is where the RSpec tests live
• README.md provides the tool overview page seen on GitHub

Common to the <tool>/lib/ folder, you will find:

• assets/ contains static files, like templates, that are used by the code at run time
• <tool>/commands_generator.rb defines the entry point for the tool by wiring up its command line handling. fastlane needs to be able to locate a file at exactly this path for any tool that can be invoked via fastlane <tool>
• <tool>/detect_values.rb serves to detect, generate, refine, or validate inputs for the tool, often working with values that were passed in as configuration parameters. It’s not needed for every tool
• <tool>/options.rb defines the configuration parameters that can be provided for the tool from the command line. This file is also typically reused to define the same parameters for a tool’s corresponding action
• <tool>.rb requires the majority of the files needed for the tool’s operation, and sets up its top-level modules, objects, and constants

So there you have it — a short tour of fastlane, with a bit of history thrown in for good measure. Hopefully this introduction has given you the guideposts you need to start exploring the code base in earnest.

fastlane is always looking to get more people involved in the community. If you’re interested in contributing, we’re always happy to have help responding to issues, reviewing pull requests, as well as making PRs to fix bugs and keep improving. I hope to see you there!