

New to pantograph? Click here to open the installation & setup instructions first

1) Install the latest Xcode command line tools

xcode-select --install

Install _pantograph_ using Homebrew & Rubygems

# Install ruby via homebrew (macOS & linux only)
brew install ruby

# Set ruby in your shell path (example uses Zsh)
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

# Using RubyGems
gem install pantograph

3) Navigate to your project and run

pantograph init

More Details

Lanes

Passing Parameters

To pass parameters from the command line to your lane, use the following syntax:

pantograph [lane] key:value key2:value2

pantograph deploy submit:false build_number:24

To access those values, change your lane declaration to also include |options|

before_all do |lane, options|
  # ...
end

before_each do |lane, options|
  # ...
end

lane :deploy do |options|
  # ...
  if options[:submit]
    # Only when submit is true
  end
  # ...
  git_tag_exists(tag: options[:build_number])
  # ...
end

after_all do |lane, options|
  # ...
end

after_each do |lane, options|
  # ...
end

error do |lane, exception, options|
  if options[:debug]
    puts "Hi :)"
  end
end

Switching lanes

To switch lanes while executing a lane, use the following code:

lane :deploy do |options|
  # ...
  build(release: true) # that's the important bit
  artifactory
  # ...
end

lane :staging do |options|
  # ...
  build # it also works when you don't pass parameters
  artifactory
  # ...
end

lane :build do |options|
  scheme = (options[:release] ? 'Release' : 'Staging')
  custom_build_actions(scheme: scheme)
end

pantograph takes care of all the magic for you. You can call lanes of the same platform or a general lane outside of the platform definition.

Passing parameters is optional.

Returning values

Additionally, you can retrieve the return value. In Ruby, the last line of the lane definition is the return value. Here is an example:

lane :deploy do |options|
  value = calculate(value: 3)
  puts value # => 5
end

lane :calculate do |options|
  # ...
  2 + options[:value] # the last line will always be the return value
end

Stop executing a lane early

The next keyword can be used to stop executing a lane before it reaches the end.

lane :build do |options|
  if cached_build_available?
    UI.important('Skipping build because a cached build is available!')
    next # skip doing the rest of this lane
  end

  gradle
end

private_lane :cached_build_available? do |options|
  # ...
  true
end

When next is used during a lane switch, control returns to the previous lane that was executing.

lane :first_lane do |options|
  UI.message('If you run: "pantograph first_lane"')
  UI.message("You'll see this!")

  second_lane
  UI.message('As well as this!')
end

private_lane :second_lane do |options|
  next
  UI.message('This will not be shown')
end

When you stop executing a lane early with next, any after_each and after_all blocks you have will still trigger as usual :+1:

before_each and after_each blocks

before_each blocks are called before any lane is called. This would include being called before each lane you've switched to.

before_each do |lane, options|
  # ...
end

after_each blocks are called after any lane is called. This would include being called after each lane you've switched to. Just like after_all, after_each is not called if an error occurs. The error block should be used in this case.

after_each do |lane, options|
  # ...
end

e.g. With this scenario, before_each and after_each would be called 4 times: before the deploy lane, before the switch to archive, sign, and upload, and after each of these lanes as well.

lane :deploy do
  archive
  sign
  upload
end

lane :archive do
  # ...
end

lane :sign do
  # ...
end

lane :upload do
  # ...
end

Lane Properties

It can be useful to dynamically access properties of the current lane. These are available in lane_context:

lane_context[SharedValues::PLATFORM_NAME]        # Platform name, e.g. `:linux` or empty (for root level lanes)
lane_context[SharedValues::LANE_NAME]            # The name of the current lane preceded by the platform name (stays the same when switching lanes)
lane_context[SharedValues::DEFAULT_PLATFORM]     # Default platform

and environment variables:

ENV['PANTOGRAPH_PLATFORM_NAME']
ENV['PANTOGRAPH_LANE_NAME']

Lane Context

The different actions can communicate with each other using a shared hash. You can access this in your lanes with the following code:

lane_context[SharedValues::VARIABLE_NAME_HERE]

Here are some examples:

lane_context[SharedValues::BUILD_NUMBER]                # Generated by `increment_build_number`
lane_context[SharedValues::VERSION_NUMBER]              # Generated by `increment_version_number`
lane_context[SharedValues::SNAPSHOT_SCREENSHOTS_PATH]   # Generated by _snapshot_
lane_context[SharedValues::GRADLE_APK_OUTPUT_PATH]      # Generated by `gradle`
lane_context[SharedValues::GRADLE_ALL_APK_OUTPUT_PATHS] # Generated by `gradle`
lane_context[SharedValues::GRADLE_FLAVOR]               # Generated by `gradle`
lane_context[SharedValues::GRADLE_BUILD_TYPE]           # Generated by `gradle`

To get information about available lane variables, run pantograph action [action_name].

Private lanes

Sometimes you might have a lane that is used from different lanes, for example:

lane :dev do
  # ...
  deploy(environment: 'dev')
  # ...
end

lane :production do
  # ...
  deploy(environment: 'production')
  # ...
end

lane :deploy do |options|
  # ...
  deploy_angular(target: options[:environment])
  # ...
end

It probably doesn't make sense to execute the build lane directly using pantograph build. You can hide this lane using

private_lane :build do |options|
  # ...
end

This will hide the lane from:

• pantograph lanes
• pantograph list
• pantograph docs

And also, you can't call the private lane using pantograph build.

The resulting private lane can only be called from another lane using the lane switching technology.

Control configuration by lane and by platform

In general, configuration files take only the first value given for a particular configuration item. That means that for an MyConfigFile like the following:

app_identifier 'com.used.id'
app_identifier 'com.ignored.id'

the app_identfier will be "com.used.id" and the second value will be ignored. The for_lane and for_platform configuration blocks provide a limited exception to this rule.

All configuration files (like: MyConfigFile) can use for_lane and for_platform blocks to control (and override) configuration values for those circumstances.

for_lane blocks will be called when the name of lane invoked on the command line matches the one specified by the block. So, given a Screengrabfile like:

locales ['en-US', 'fr-FR', 'ja-JP']

for_lane :screenshots_english_only do
  locales ['en-US']
end

for_lane :screenshots_french_only do
  locales ['fr-FR']
end

locales will have the values ['en-US', 'fr-FR', 'ja-JP'] by default, but will only have one value when running the pantograph screenshots_english_only or pantograph screenshots_french_only.