Actions

There are lots of predefined fastlane actions you can use. If you have ideas for more, please let me know.

To get the most up-to-date information from the command line on your current verion you can also run:

fastlane actions: List all available fastlane actions
fastlane action [action_name]:

Building
Testing
Deploying
Modifying Project
Developer Portal
Using git
Using mercurial
Notifications
Misc

Building

Bundler

This will install your Gemfile by executing bundle install

bundle_install

CocoaPods

Everyone using CocoaPods will probably want to run a pod install before running tests and building the app.

cocoapods # this will run pod install

Carthage

This will execute carthage bootstrap

carthage

More options are available:

carthage(
  use_ssh: false,         # Use SSH for downloading GitHub repositories.
  use_submodules: false,  # Add dependencies as Git submodules.
  use_binaries: true,     # Check out dependency repositories even when prebuilt frameworks exist
  platform: "all"         # Define which platform to build for
)

xctool

You can run any xctool action. This will require having xctool installed through homebrew.

xctool :test

It is recommended to have the xctool configuration stored in a .xctool-args file.

If you prefer to have the build configuration stored in the Fastfile:

xctool :test, [
      "--workspace", "'AwesomeApp.xcworkspace'",
      "--scheme", "'Schema Name'",
      "--configuration", "Debug",
      "--sdk", "iphonesimulator",
      "--arch", "i386"
    ].join(" ")

snapshot

snapshot

To make snapshot work without user interaction, follow the CI-Guide of snapshot.

To skip cleaning the project on every build use snapshot(noclean: true).

To show the output of UIAutomation use snapshot(verbose: true).

Other options

snapshot(
  nobuild: true, # Skip building and use a pre-built .app under your 'build_dir'
  noclean: true, # Skip cleaning
  verbose: true, # Show output of UIAutomation
  snapshot_file_path: './folder/containing/Snapfile' # Specify a path to the directory containing the Snapfile
)

Take a look at the prefilling data guide on the snapshot documentation.

gym

gym builds and packages iOS apps for you. It takes care of all the heavy lifting and makes it super easy to generate a signed ipa file.

gym(scheme: "MyApp", workspace: "MyApp.xcworkspace")

There are many more options available, you can use gym --help to get the latest list of available options.

gym(
  workspace: "MyApp.xcworkspace",
  configuration: "Debug",
  scheme: "MyApp",
  silent: true,
  clean: true,
  output_directory: "path/to/dir", # Destination directory. Defaults to current directory.
  output_name: "my-app.ipa",       # specify the name of the .ipa file to generate (including file extension)
  sdk: "10.0"                     # use SDK as the name or path of the base SDK when building the project.
)

Use gym --help to get all available options.

The alternative to gym is ipa which uses shenzhen under the hood.

ipa

Build your app right inside fastlane and the path to the resulting ipa is automatically available to all other actions.

You should check out the code signing guide.

ipa(
  workspace: "MyApp.xcworkspace",
  configuration: "Debug",
  scheme: "MyApp",
  # (optionals)
  clean: true,                     # This means 'Do Clean'. Cleans project before building (the default if not specified).
  destination: "path/to/dir",      # Destination directory. Defaults to current directory.
  ipa: "my-app.ipa",               # specify the name of the .ipa file to generate (including file extension)
  xcargs: "MY_ADHOC=0",            # pass additional arguments to xcodebuild when building the app.
  embed: "my.mobileprovision",     # Sign .ipa file with .mobileprovision
  identity: "MyIdentity",          # Identity to be used along with --embed
  sdk: "10.0",                     # use SDK as the name or path of the base SDK when building the project.
  archive: true                    # this means 'Do Archive'. Archive project after building (the default if not specified).
)

The ipa action uses shenzhen under the hood.

The path to the ipa is automatically used by Crashlytics, Hockey and DeployGate.

Important:

To also use it in deliver, update your Deliverfile and remove all code in the Building and Testing section, in particular all ipa and beta_ipa blocks.

See how Product Hunt uses the ipa action.

update_project_provisioning

You should check out the code signing guide before using this action.

Updates your Xcode project to use a specific provisioning profile for code signing, so that you can properly build and sign the .ipa file using the ipa action or a CI service.

Since you have to use different provisioning profiles for various targets (WatchKit, Extension, etc.) and configurations (Debug, Release) you can use the target_filter and build_configuration options:

update_project_provisioning(
  xcodeproj: "Project.xcodeproj",
  profile: "./watch_app_store.mobileprovision", # optional if you use sigh
  target_filter: ".*WatchKit Extension.*", # matches name or type of a target
  build_configuration: "Release"
)

The target_filter and build_configuration options use standard regex, so if you want an exact match for a target, use ^MyTargetName$ to prevent a match for the Pods - MyTargetName target, for instance.

Example Usage at MindNode

update_app_group_identifiers

Updates the App Group Identifiers in the given Entitlements file, so you can have app groups for the app store build and app groups for an enterprise build.

update_app_group_identifiers(
	entitlements_file: '/path/to/entitlements_file.entitlements',
	app_group_identifiers: ['group.your.app.group.identifier'])

xcode_select

Use this command if you are supporting multiple versions of Xcode

xcode_select "/Applications/Xcode6.1.app"

resign

This will resign an ipa with another signing identity and provisioning profile.

If you have used the ipa and sigh actions, then this action automatically gets the ipa and provisioning_profile values respectively from those actions and you don't need to manually set them (although you can always override them).

resign(
  ipa: 'path/to/ipa', # can omit if using the `ipa` action
  signing_identity: 'iPhone Distribution: Luka Mirosevic (0123456789)',
  provisioning_profile: 'path/to/profile', # can omit if using the `sigh` action
)

`create_keychain`

Create a new keychain, which can then be used to import certificates.

create_keychain(
  name: "KeychainName",
  default_keychain: true,
  unlock: true,
  timeout: 3600,
  lock_when_sleeps: true
)

`unlock_keychain`

Unlock existing keychain and add it to the keychain search list.

unlock_keychain(
  path: "/path/to/KeychainName.keychain",
  password: "mysecret"
)

If the keychain file is located in the standard location ~/Library/Keychains, then it is sufficient to provide the keychain file name, or file name with suffix.

unlock_keychain(
  path: "KeychainName",
  password: "mysecret"
)

`delete_keychain`

Delete a keychain, can be used after creating one with create_keychain.

delete_keychain(name: "KeychainName")

`import_certificate`

Import certificates into the current default keychain. Use create_keychain to create a new keychain.

import_certificate certificate_path: "certs/AppleWWDRCA.cer"
import_certificate certificate_path: "certs/dist.p12", certificate_password: ENV['CERT_PASSWORD']

xcodebuild

Enables the use of the xcodebuild tool within fastlane to perform xcode tasks such as; archive, build, clean, test, export & more.

You should check out the code signing guide.

# Create an archive. (./build-dir/MyApp.xcarchive)
xcodebuild(
  archive: true,
  archive_path: './build-dir/MyApp.xcarchive',
  scheme: 'MyApp',
  workspace: 'MyApp.xcworkspace'
)

build_settings are variables which are exposed inside the build process as ENV variables, and can be used to override project settings, or dynamically set values inside a Plist.

output_style sets the output format of the console output. Supported options are: 1) :standard, this is the default and will output pretty colored UTF8, and 2) :basic, which will output monochrome ASCII, useful for a CI environment like TeamCity that doesn't support color/UTF8.

xcodebuild(
  workspace: "...",
  scheme: "...",
  build_settings: {
    "CODE_SIGN_IDENTITY" => "iPhone Developer: ...",
    "PROVISIONING_PROFILE" => "...",
    "JOBS" => 16
  },
  output_style: :basic
)

To keep your Fastfile lightweight, there are also alias actions available for the most common xcodebuild operations: xcarchive, xcbuild, xcclean, xctest & xcexport.

Environment variables may be added to a .env file in place of some parameters:

XCODE_PROJECT="./MyApp.xcodeproj"
XCODE_WORKSPACE="./MyApp.xcworkspace"
XCODE_SCHEME="MyApp"
XCODE_BUILD_PATH="./build"

More usage examples (assumes the above .env setup is being used):

  # Clean the project
  xcclean

  # Build the project
  xcbuild

  # Run tests in given simulator
  xctest(
    destination: "name=iPhone 5s,OS=8.1"
  )

  # Create an archive (./build-dir/MyApp.xcarchive)
  xcarchive

  # Export a signed binary (./build-dir/MyApp.ipa)
  xcexport

See how Wikipedia uses the xctest action to test their app.

clean_build_artifacts

This action deletes the files that get created in your repo as a result of running the ipa and sigh commands. It doesn't delete the fastlane/report.xml though, this is probably more suited for the .gitignore.

Useful if you quickly want to send out a test build by dropping down to the command line and typing something like fastlane beta, without leaving your repo in a messy state afterwards.

clean_build_artifacts

See how Artsy cleans their build artifacts after building and distributing their app.

frameit

By default, the device color will be black

frameit

To use white (sorry, silver) device frames

frameit :silver

See how MindNode uses frameit to not only frame the screenshots, but also add a title and a background around the screenshots. More information available in their Fastfile and the screenshots folder (Framefile.json)

dsym_zip

Create a zipped dSYM file from your .xcarchive, useful if you use the xcodebuild action in combination with crashlytics or hockey.

dsym_zip

You can manually specify the path to the xcarchive (not needed if you use xcodebuild/xcarchive to build your archive):

dsym_zip(
  archive_path: 'MyApp.xcarchive'
)

Testing

xctest

Use the xctest command to run unit tests.

When running tests, coverage reports can be generated via xcpretty reporters:

  # Run tests in given simulator
  xctest(
    destination: "name=iPhone 5s,OS=8.1",
    destination_timeout: 120, # increase device/simulator timeout, usually used on slow CI boxes
    reports: [{
      report: 'html',
      output: './build-dir/test-report.html',  # will use XCODE_BUILD_PATH/report, if output is not provided
      screenshots: 1
    },
    {
      report: 'junit',
      output: './build-dir/test-report.xml'
    }]
  )

gcovr

Generate summarized code coverage reports.

gcovr(
  html: true,
  html_details: true,
  output: "./code-coverage/report.html"
)

lcov

Generate code coverage reports based on lcov.

lcov(
      project_name: "yourProjectName",
      scheme: "yourScheme",
      output_dir: "cov_reports" # This value is optional. Default is coverage_reports
)

OCLint

Run the static analyzer tool OCLint for your project. You need to have a compile_commands.json file in your fastlane directory or pass a path to your file.

oclint(
  compile_commands: 'commands.json', # The json compilation database, use xctool reporter 'json-compilation-database'
  select_reqex: /ViewController.m/,  # Select all files matching this reqex
  report_type: 'pmd',                # The type of the report (default: html)
  max_priority_1: 10,                # The max allowed number of priority 1 violations
  max_priority_2: 100,               # The max allowed number of priority 2 violations
  max_priority_3: 1000,              # The max allowed number of priority 3 violations
  rc: 'LONG_LINE=200'                # Override the default behavior of rules
)

`ensure_no_debug_code`

You don't want any debug code to slip into production. You can use the ensure_no_debug_code action to make sure no debug code is in your code base before deploying it:

ensure_no_debug_code(text: "// TODO")

ensure_no_debug_code(text: "NSLog",
                     path: "./lib",
                extension: "m")

Deploying

pilot

pilot(username: "felix@krausefx.com",
      app_identifier: "com.krausefx.app")

More information about the available options fastlane action pilot and a more detailed description on the pilot project page.

deliver

deliver

To upload a new build to TestFlight use deliver(beta: true).

If you don't want a PDF report for App Store builds, append :force to the command. This is useful when running fastlane on your Continuous Integration server: deliver(force: true)

Other options

deliver(
  force: true,# Set to true to skip PDF verification
  skip_deploy: true, # To don't submit the app for review (works with both App Store and beta builds)
  deliver_file_path: './nothere' # Specify a path to the directory containing the Deliverfile
)

If you want to use a different Apple ID for iTunes Connect in deliver, just add this to your Deliverfile:

email "itunes@connect.com"

If you only want to upload a binary without any metadata, use deliver(beta: true, skip_deploy: true)

See how Product Hunt automated the building and distributing of a beta version over TestFlight in their Fastfile.

TestFlight

To upload a new binary to Apple TestFlight use the testflight action:

testflight

This will use deliver under the hood.

Additionally you can skip the submission of the new binary to the testers to only upload the build:

testflight(skip_deploy: true)

HockeyApp

hockey(
  api_token: '...',
  ipa: './app.ipa',
  notes: "Changelog"
)

Symbols will also be uploaded automatically if a app.dSYM.zip file is found next to app.ipa. In case it is located in a different place you can specify the path explicitly in :dsym parameter.

More information about the available options can be found in the HockeyApp Docs.

See how Artsy distributes new builds via Hockey in their Fastfile.

Crashlytics Beta

crashlytics(
  crashlytics_path: './Crashlytics.framework', # path to your 'Crashlytics.framework'
  api_token: '...',
  build_secret: '...',
  ipa_path: './app.ipa'
)

Additionally you can specify notes_path, emails, groups and notifications.

The following environment variables may be used in place of parameters: CRASHLYTICS_API_TOKEN, CRASHLYTICS_BUILD_SECRET, and CRASHLYTICS_FRAMEWORK_PATH.

AWS S3 Distribution

Upload a new build to Amazon S3 to distribute the build to beta testers. Works for both Ad Hoc and Enterprise signed applications. This step will generate the necessary HTML, plist, and version files for you.

Add the s3 action after the ipa step:

s3

You can also customize a lot of options:

s3(
  # All of these are used to make Shenzhen's `ipa distribute:s3` command
  access_key: ENV['S3_ACCESS_KEY'],               # Required from user.
  secret_access_key: ENV['S3_SECRET_ACCESS_KEY'], # Required from user.
  bucket: ENV['S3_BUCKET'],                       # Required from user.
  ipa: 'AppName.ipa',                             # Optional is you use `ipa` to build
  dsym: 'AppName.app.dSYM.zip',                   # Optional is you use `ipa` to build
  path: 'v{CFBundleShortVersionString}_b{CFBundleVersion}/', # This is actually the default.
  upload_metadata: true,                          # Upload version.json, plist and HTML. Set to false to skip uploading of these files.
  version_file_name: 'app_version.json',          # Name of the file to upload to S3. Defaults to 'version.json'
  version_template_path: 'path/to/erb'            # Path to an ERB to configure the structure of the version JSON file
)

It is recommended to not store the AWS access keys in the Fastfile.

The uploaded version.json file provides an easy way for apps to poll if a new update is available. The JSON looks like:

{
    "latestVersion": "<%= full_version %>",
    "updateUrl": "itms-services://?action=download-manifest&url=<%= url %>"
}

DeployGate

You can retrieve your username and API token on your settings page.

deploygate(
  api_token: '...',
  user: 'target username or organization name',
  ipa: './ipa_file.ipa',
  message: "Build #{lane_context[SharedValues::BUILD_NUMBER]}",
)

If you put deploygate after ipa action, you don't have to specify IPA file path, as it is extracted from the lane context automatically.

More information about the available options can be found in the DeployGate Push API document.

Xcode Server get assets

This action retrieves integration assets (.xcarchive, logs etc) from your Xcode Server instance over HTTPS.

xcode_server_get_assets(
    host: '10.99.0.59', # Specify Xcode Server's Host or IP Address
    bot_name: 'release-1.3.4' # Specify the particular Bot
  )

This allows you to use Xcode Server for building and testing, which can be useful when your build takes a long time and requires connected iOS devices for testing. This action only requires you specify the host and the bot_name and it will go and download, unzip and return a path to the downloaded folder. Then you can export an IPA from the archive and upload it with deliver.

Run fastlane action xcode_server_get_assets for the full list of options.

set_changelog

To easily set the changelog of an app on iTunes Connect for all languages

set_changelog(app_identifier: "com.krausefx.app", version: "1.0", changelog: "All Languages")

You can store the changelog in ./fastlane/changelog.txt and it will automatically get loaded from there. This integration is useful if you support e.g. 10 languages and want to use the same "What's new"-text for all languages.

Modifying Project

increment_build_number

This method will increment the build number, not the app version. Usually this is just an auto incremented number. You first have to set up your Xcode project, if you haven't done it already.

increment_build_number # automatically increment by one
increment_build_number(
  build_number: '75' # set a specific number
)

increment_build_numer(
  build_number: 75, # specify specific build number (optional, omitting it increments by one)
  xcodeproj: './path/to/MyApp.xcodeproj' # (optional, you must specify the path to your main Xcode project if it is not in the project root directory)
)

See how Wikpedia uses the increment_build_number action.

You can also only receive the build number without modifying it

version = get_build_number(xcodepoj: "Project.xcodeproj")

increment_version_number

This action will increment the version number. You first have to set up your Xcode project, if you haven't done it already.

increment_version_number # Automatically increment patch version number.
increment_version_number(
  bump_type: "patch" # Automatically increment patch version number
)
increment_version_number(
  bump_type: "minor" # Automatically increment minor version number
)
increment_version_number(
  bump_type: "major" # Automatically increment major version number
)
increment_version_number(
  version_number: '2.1.1' # Set a specific version number
)

increment_version_number(
  version_number: '2.1.1',                # specify specific version number (optional, omitting it increments patch version number)
  xcodeproj: './path/to/MyApp.xcodeproj'  # (optional, you must specify the path to your main Xcode project if it is not in the project root directory)
)

See how Wikpedia uses the increment_version_number action.

You can also only receive the version number without modifying it

version = get_version_number(xcodepoj: "Project.xcodeproj")

set_build_number_repository

set_build_number_repository

This action will set the build number according to what the SCM HEAD reports. Currently supported SCMs are svn (uses root revision), git-svn (uses svn revision) and git (uses short hash).

There are no options currently available for this action.

Developer Portal

sigh

This will generate and download your App Store provisioning profile. sigh will store the generated profile in the current folder.

sigh

You can pass all options listed in sigh --help in fastlane:

sigh(
  adhoc: true,
  force: true,
  filename: "myFile.mobileprovision"
)

See how Wikpedia uses sigh to automatically retrieve the latest provisioning profile.

PEM

This will generate a new push profile if necessary (the old one is about to expire).

Use it like this:

pem

pem(
  force: true, # create a new profile, even if the old one is still valid
  app_identifier: 'net.sunapps.9', # optional app identifier,
  save_private_key: true,
  new_profile: Proc.new do |profile_path| # this block gets called when a new profile was generated
    puts profile_path # the absolute path to the new PEM file
    # insert the code to upload the PEM file to the server
  end
)

Use the fastlane action pem command to view all available options.

Product Hunt uses PEM to automatically create a new push profile for Parse.com if necessary before a release.

cert

The cert action can be used to make sure to have the latest signing certificate installed. More information on the cert project page.

cert

fastlane will automatically pass the signing certificate to use to sigh.

You can pass all options listed in sigh --help in fastlane:

cert(
  development: true,
  username: "user@email.com"
)

produce

Create new apps on iTunes Connect and Apple Developer Portal. If the app already exists, produce will not do anything.

produce(
  username: 'felix@krausefx.com',
  app_identifier: 'com.krausefx.app',
  app_name: 'MyApp',
  language: 'English',
  version: '1.0',
  sku: 123,
  team_name: 'SunApps GmbH' # Only necessary when in multiple teams.
)

SunApps uses produce to automatically generate new apps for new customers.

register_devices

This will register iOS devices with the Developer Portal so that you can include them in your provisioning profiles.

This is an optimistic action, in that it will only ever add new devices to the member center, and never remove devices. If a device which has already been registered within the member center is not passed to this action, it will be left alone in the member center and continue to work.

The action will connect to the Apple Developer Portal using the username you specified in your Appfile with apple_id, but you can override it using the username option, or by setting the env variable ENV['DELIVER_USER'].

# Simply provide a list of devices as a Hash
register_devices(
  devices: {
    'Luka iPhone 6' => '1234567890123456789012345678901234567890',
    'Felix iPad Air 2' => 'abcdefghijklmnopqrstvuwxyzabcdefghijklmn',
  }
)

# Alternatively provide a standard UDID export .txt file, see the Apple Sample (https://devimages.apple.com.edgekey.net/downloads/devices/Multiple-Upload-Samples.zip)
register_devices(
  devices_file: './devices.txt'
)

# Advanced
register_devices(
  devices_file: './devices.txt', # You must pass in either `devices_file` or `devices`.
  team_id: 'XXXXXXXXXX',         # Optional, if you're a member of multiple teams, then you need to pass the team ID here.
  username: 'luka@goonbee.com'   # Optional, lets you override the Apple Member Center username.
)

Using git

ensure_git_branch

This action will check if your git repo is checked out to a specific branch. You may only want to make releases from a specific branch, so ensure_git_branch will stop a lane if it was accidentally executed on an incorrect branch.

ensure_git_branch # defaults to `master` branch

ensure_git_branch(
  branch: 'develop'
)

last_git_tag

Simple action to get the latest git tag

last_git_tag

git_branch

Quickly get the name of the branch you're currently in

git_branch

ensure_git_status_clean

A sanity check to make sure you are working in a repo that is clean. Especially useful to put at the beginning of your Fastfile in the before_all block, if some of your other actions will touch your filesystem, do things to your git repo, or just as a general reminder to save your work. Also needed as a prerequisite for some other actions like reset_git_repo.

ensure_git_status_clean

Wikipedia uses ensure_git_status_clean to make sure, no uncommited changes are deployed by `fastlane.

commit_version_bump

This action will create a "Version Bump" commit in your repo. Useful in conjunction with increment_build_number.

It checks the repo to make sure that only the relevant files have changed, these are the files that increment_build_number (agvtool) touches:

All .plist files
The .xcodeproj/project.pbxproj file

Then commits those files to the repo.

Customise the message with the :message option, defaults to "Version Bump"

If you have other uncommitted changes in your repo, this action will fail. If you started off in a clean repo, and used the ipa and or sigh actions, then you can use the clean_build_artifacts action to clean those temporary files up before running this action.

commit_version_bump

commit_version_bump(
  message: 'Version Bump',                    # create a commit with a custom message
  xcodeproj: './path/to/MyProject.xcodeproj', # optional, if you have multiple Xcode project files, you must specify your main project here
)

Artsy uses fastlane to automatically commit the version bump, add a new git tag and push everything back to master.

add_git_tag

This will automatically tag your build with the following format: <grouping>/<lane>/<prefix><build_number>, where:

grouping is just to keep your tags organised under one "folder", defaults to 'builds'
lane is the name of the current fastlane lane
prefix is anything you want to stick in front of the version number, e.g. "v"
build_number is the build number, which defaults to the value emitted by the increment_build_number action

For example for build 1234 in the "appstore" lane it will tag the commit with builds/appstore/1234

add_git_tag # simple tag with default values

add_git_tag(
  grouping: 'fastlane-builds',
  prefix: 'v',
  build_number: 123
)

Alternatively, you can specify your own tag. Note that if you do specify a tag, all other arguments are ignored.

add_git_tag(
  tag: 'my_custom_tag',
)

Artsy uses fastlane to automatically commit the version bump, add a new git tag and push everything back to master.

push_to_git_remote

Lets you push your local commits to a remote git repo. Useful if you make local changes such as adding a version bump commit (using commit_version_bump) or a git tag (using 'add_git_tag') on a CI server, and you want to push those changes back to your canonical/main repo.

Tags will be pushed as well.

push_to_git_remote # simple version. pushes 'master' branch to 'origin' remote

push_to_git_remote(
  remote: 'origin',         # optional, default: 'origin'
  local_branch: 'develop',  # optional, aliased by 'branch', default: 'master'
  remote_branch: 'develop', # optional, default is set to local_branch
  force: true,              # optional, default: false
)

Artsy uses fastlane to automatically commit the version bump, add a new git tag and push everything back to master.

push_git_tags

If you only want to push the tags and nothing else, you can use the push_git_tags action:

push_git_tags

reset_git_repo

This action will reset your git repo to a clean state, discarding any uncommitted and untracked changes. Useful in case you need to revert the repo back to a clean state, e.g. after the fastlane run.

It's a pretty drastic action so it comes with a sort of safety latch. It will only proceed with the reset if either of these conditions are met:

You have called the ensure_git_status_clean action prior to calling this action. This ensures that your repo started off in a clean state, so the only things that will get destroyed by this action are files that are created as a byproduct of the fastlane run.
You call it with the force: true option, in which case "you have been warned".

Also useful for putting in your error block, to bring things back to a pristine state (again with the caveat that you have called ensure_git_status_clean before)

reset_git_repo
reset_git_repo :force # If you don't care about warnings and are absolutely sure that you want to discard all changes. This will reset the repo even if you have valuable uncommitted changes, so use with care!

# You can also specify a list of files that should be resetted.
reset_git_repo(
  force: true,
  files: [
    "./file.txt"
  ])

MindNode uses this action to reset temporary changes of the project configuration after successfully building it.

get_github_release

You can easily receive information about a specific release from GitHub.com

release = get_github_release(url: "KrauseFx/fastlane", version: "1.0.0")
puts release['name']

To get a list of all available values run fastlane action get_github_release.

Using mercurial

hg_ensure_clean_status

Along the same lines as the ensure_git_status_clean action, this is a sanity check to ensure the working mercurial repo is clean. Especially useful to put at the beginning of your Fastfile in the before_all block.

hg_ensure_clean_status

hg_commit_version_bump

The mercurial equivalent of the commit_version_bump git action. Like the git version, it is useful in conjunction with increment_build_number.

It checks the repo to make sure that only the relevant files have changed, these are the files that increment_build_number (agvtool) touches:

All .plist files
The .xcodeproj/project.pbxproj file

Then commits those files to the repo.

Customise the message with the :message option, defaults to "Version Bump"

If you have other uncommitted changes in your repo, this action will fail. If you started off in a clean repo, and used the ipa and or sigh actions, then you can use the clean_build_artifacts action to clean those temporary files up before running this action.

hg_commit_version_bump

hg_commit_version_bump(
  message: 'Version Bump',                    # create a commit with a custom message
  xcodeproj: './path/to/MyProject.xcodeproj', # optional, if you have multiple Xcode project files, you must specify your main project here
)

hg_add_tag

A simplified version of git action add_git_tag. It adds a given tag to the mercurial repo.

Specify the tag name with the :tag option.

hg_add_tag tag: version_number

hg_push

The mercurial equivalent of push_to_git_remote — pushes your local commits to a remote mercurial repo. Useful when local changes such as adding a version bump commit or adding a tag are part of your lane’s actions.

hg_push # simple version. pushes commits from current branch to default destination

hg_push(
  destination: 'ssh://hg@repohost.com/owner/repo', # optional
  force: true,                                     # optional, default: false
)

Notifications

Slack

Create an Incoming WebHook and export this as SLACK_URL. Can send a message to #channel (by default), a direct message to @username or a message to a private group group with success (green) or failure (red) status.

slack(
  message: "App successfully released!"
)

slack(
  message: "App successfully released!",
  channel: "#channel",  # Optional, by default will post to the default channel configured for the POST URL.
  success: true,        # Optional, defaults to true.
  payload: {            # Optional, lets you specify any number of your own Slack attachments.
    'Build Date' => Time.new.to_s,
    'Built by' => 'Jenkins',
  },
  default_payloads: [:git_branch, :git_author], # Optional, lets you specify a whitelist of default payloads to include. Pass an empty array to suppress all the default payloads. Don't add this key, or pass nil, if you want all the default payloads. The available default payloads are: `lane`, `test_result`, `git_branch`, `git_author`, `last_git_commit`.
  attachment_properties: { # Optional, lets you specify any other properties available for attachments in the slack API (see https://api.slack.com/docs/attachments). This hash is deep merged with the existing properties set using the other properties above. This allows your own fields properties to be appended to the existings fields that were created using the `payload` property for instance.
    thumb_url: 'http://example.com/path/to/thumb.png',
    fields: [{
      title: 'My Field',
      value: 'My Value',
      short: true
    }]
  }
)

Take a look at the example projects of how you can use the slack action, for example the MindNode configuration.

Mailgun

Send email notifications right from fastlane using Mailgun.

ENV['MAILGUN_SANDBOX_POSTMASTER'] ||= "MY_POSTMASTER"
ENV['MAILGUN_APIKEY'] = "MY_API_KEY"
ENV['MAILGUN_APP_LINK'] = "MY_APP_LINK"

mailgun(
  to: "fastlane@krausefx.com",
  success: true,
  message: "This is the mail's content"
)

or

mailgun(
  postmaster: "MY_POSTMASTER",
  apikey: "MY_API_KEY",
  to: "DESTINATION_EMAIL",
  success: true,
  message: "Mail Body",
  app_link: "http://www.myapplink.com",
  ci_build_link: "http://www.mycibuildlink.com"
)

HipChat

Send a message to room (by default) or a direct message to @username with success (green) or failure (red) status.

  ENV["HIPCHAT_API_TOKEN"] = "Your API token"
  ENV["HIPCHAT_API_VERSION"] = "1 for API version 1 or 2 for API version 2"

  hipchat(
    message: "App successfully released!",
    channel: "Room or @username",
    success: true
  )

Typetalk

Send a message to topic with success (:smile:) or failure (:rage:) status. Using Bot's Typetalk Token

  typetalk(
    message: "App successfully released!",
    note_path: 'ChangeLog.md',
    topicId: 1,
    success: true,
    typetalk_token: 'Your Typetalk Token'
  )

ChatWork

Post a message to a group chat.

How to authenticate ChatWork API

  ENV["CHATWORK_API_TOKEN"] = "Your API token"

  chatwork(
    message: "App successfully released!",
    roomid: 12345,
    success: true
  )

Notify

Display a notification using the OS X notification centre. Uses terminal-notifier.

  notify "Finished driving lane"

ByMyEyes uses the notify action to show a success message after fastlane finished executing.

Testmunk

Run your functional tests on real iOS devices over the cloud (for free on an iPod). With this simple testcase you can ensure your app launches and there is no crash at launch. Tests can be extended with Testmunk's library or custom steps. More details about this action can be found in testmunk.rb.

ENV['TESTMUNK_EMAIL'] = 'email@email.com'
# Additionally, you have to set TESTMUNK_API, TESTMUNK_APP and TESTMUNK_IPA
testmunk

Other

update_fastlane

This action will look at all installed fastlane tools and update them to the next available minor version - major version updates will not be performed automatically, as they might include breaking changes. If an update was performed, fastlane will be restarted before the run continues.

If you are using rbenv or rvm, everything should be good to go. However, if you are using the system's default ruby, some additional setup is needed for this action to work correctly. In short, fastlane needs to be able to access your gem library without running in sudo mode.

The simplest possible fix for this is putting the following lines into your ~/.bashrc or ~/.zshrc file:

export GEM_HOME=~/.gems
export PATH=$PATH:~/.gems/bin

After the above changes, restart your terminal, then run mkdir $GEM_HOME to create the new gem directory. After this, you're good to go!

Recommended usage of the update_fastlane action is at the top of the before_all block, before running any other action:

before_all do
  update_fastlane

  cocoapods
  increment_build_number
  ...
end

Misc

say

To speak out a text

say "I can speak"

clipboard

You can store a string in the clipboard running

clipboard(value: "https://github.com/KrauseFx/fastlane")

This can be used to store some generated URL or value for easy copy & paste (e.g. the download link):

clipboard(value: lane_context[SharedValues::HOCKEY_DOWNLOAD_LINK])

is_ci?

Is the current run being executed on a CI system, like Jenkins or Travis?

if is_ci?
  puts "I'm a computer"
else
  say "Hi Human!"
end

Files

Actions.md

Latest commit

History

Actions.md

File metadata and controls

Actions

Building

ipa

update_project_provisioning

update_app_group_identifiers

create_keychain

unlock_keychain

delete_keychain

import_certificate

clean_build_artifacts

dsym_zip

Testing

xctest

ensure_no_debug_code

Deploying

TestFlight

AWS S3 Distribution

set_changelog

Modifying Project

set_build_number_repository

Developer Portal

register_devices

Using git

ensure_git_branch

last_git_tag

git_branch

ensure_git_status_clean

commit_version_bump

add_git_tag

push_to_git_remote

push_git_tags

reset_git_repo

get_github_release

Using mercurial

hg_ensure_clean_status

hg_commit_version_bump

hg_add_tag

hg_push

Notifications

Notify

Other

update_fastlane

Misc

say

clipboard

is_ci?

`create_keychain`

`unlock_keychain`

`delete_keychain`

`import_certificate`

`ensure_no_debug_code`