Lane — co to jest, tworzenie i używanie w Fastlane

Co to jest Lane w Fastlane

Lane — to podstawowy blok konstrukcyjny Fastlane, definiujący nazwany scenariusz automatyzacji. Każdy lane opisuje sekwencję działań (actions), które są wykonywane w celu osiągnięcia konkretnego celu: zbudowania aplikacji, uruchomienia testów, przesłania buildu do sklepu lub skonfigurowania środowiska. Lane jest deklarowany w Fastfile i uruchamiany poleceniem fastlane [nazwa_lane] z katalogu głównego projektu.

Koncepcja lane została zaczerpnięta z Ruby DSL i zapewnia czytelność scenariuszy. Deweloper widzi cały proces CI/CD jako sekwencję wywołań actions zrozumiałymi nazwami i parametrami. Lane może być prosty (jedno polecenie) lub złożony (rozgałęzienia, pętle, wywołania innych lanes).

Każdy lane po wykonaniu zwraca wynik — obiekt zawierający status wykonania i dane z actions. Wynik może być użyty w innych lanes lub przekazany do systemu CI/CD w celu podejmowania decyzji. Jeśli dowolne action w lane zakończy się błędem, wykonanie lane zostaje zatrzymane i wywoływany jest blok error.

Składnia lane: deklaracja i uruchamianie

Składnia deklaracji lane opiera się na prostym wzorcu Ruby DSL: słowo kluczowe lane, nazwa scenariusza w formie symbolu Ruby (symbol), blok do ... end z treścią scenariusza. Nazwa lane musi być unikalna w obrębie platformy i składać się z liter, cyfr i podkreślników.

Uruchomienie lane odbywa się przez wiersz poleceń: fastlane build (dla lane o nazwie :build) lub bundle exec fastlane build (jeśli Fastlane jest zainstalowany przez Bundler). Dla platformowych lanes użyj fastlane ios build lub fastlane android build.

# Deklaracja prostego lane
lane :test do
  scan(scheme: 'App', devices: ['iPhone 15'])
end

lane :build_and_deploy do
  cocoapods
  test
  gym(scheme: 'App', export_method: 'app-store')
  pilot(skip_waiting_for_build_processing: true)
end

# Uruchomienie: fastlane build_and_deploy

Lane może zawierać logikę warunkową opartą na parametrach lub zmiennych środowiskowych. Użyj if/unless do pomijania kroków w określonych warunkach. Dostępne są również pętle each do przetwarzania tablic, co jest wygodne przy budowaniu wielu targetów lub schematów aplikacji w jednym lane.

Zwracanie wartości z lane

Lane może zwracać wartość, która będzie dostępna dla wywołującego kodu. Do zwracania używa się standardowego Ruby return lub ostatniego wyrażenia w bloku lane. Zwracana wartość może być ciągiem znaków, liczbą, hashem lub wynikiem action. Pozwala to na wykorzystanie wyniku jednego lane w innym lane do podejmowania decyzji.

Na przykład lane :get_version może zwrócić bieżącą wersję aplikacji z Info.plist, a lane :deploy użyć jej do sformułowania wiadomości w Slacku. Zwracane wartości są szczególnie przydatne w private lanes, gdzie wynik jest potrzebny do dalszego przetwarzania w wywołującym lane.

Parametry lanes: przekazywanie i obsługa

Parametry lane sprawiają, że scenariusze są elastyczne i wielokrotnego użytku. Lane przyjmuje parametry przez options hash, który jest przekazywany podczas uruchamiania z wiersza poleceń: fastlane deploy scheme:AppStore version:2.1.0. Wewnątrz lane parametry są dostępne jako options[:scheme] i options[:version].

Dla parametrów obowiązkowych sprawdzaj obecność wartości na początku lane i wywołuj UI.user_error! z jasnym komunikatem. Dla parametrów opcjonalnych ustawiaj wartości domyślne przez operator ||. Fastlane obsługuje również typowane parametry przez metodę options z określeniem typu, wartości domyślnej i opisu.

# Lane z obsługą parametrów
lane :deploy do |options|
  scheme = options[:scheme]
  version = options[:version] || '1.0.0'
  beta = options[:beta] || false

  UI.user_error!("Nie określono scheme") unless scheme

  match(type: beta ? 'adhoc' : 'appstore')
  gym(scheme: scheme, export_method: beta ? 'ad-hoc' : 'app-store')

  if beta
    pilot(distribute_external: true)
  else
    deliver(submit_for_review: true)
  end
end

# Uruchomienie: fastlane deploy scheme:MyApp beta:true version:2.1.0

Do pracy ze zmiennymi środowiskowymi wewnątrz lane użyj ENV['VARIABLE_NAME']. Fastlane automatycznie ładuje pliki .env z katalogu fastlane. Jest to standardowy sposób przekazywania wrażliwych danych — kluczy API, haseł i tokenów — w środowisku CI/CD bez przechowywania ich w Fastfile.

Walidacja parametrów

Dla niezawodnego działania lane konieczna jest walidacja parametrów na wejściu. Użyj UI.user_error! z opisem problemu, jeśli wymagany parametr jest nieobecny lub ma nieprawidłowy typ. Fastlane udostępnia metodę options, która pozwala określić typ (String, Boolean, Integer, Array), wartość domyślną i opis dla każdego parametru — walidacja jest wykonywana automatycznie przy uruchomieniu lane.

Dodatkowo można użyć sprawdzeń przez verify blok: verify do |value| value.length > 0 end dla parametrów tekstowych. Przy nieprawidłowym formacie Fastlane wyświetla czytelny komunikat z oczekiwanym formatem i przekazaną wartością, co ułatwia debugowanie w środowisku CI/CD.

Łączenie lanes: before_all, after_all i obsługa błędów

Fastlane udostępnia haki cyklu życia do wykonywania kodu przed i po każdym lane. Blok before_all jest wykonywany przed każdym lane w danej platformie lub globalnie. Blok after_all jest wykonywany po pomyślnym zakończeniu lane. Blok error jest wykonywany przy każdym błędzie wewnątrz lane.

Haki pozwalają centralizować powtarzającą się logikę: instalacja zależności w before_all, wysyłanie powiadomień w after_all, czyszczenie plików tymczasowych i powiadamianie o błędach w bloku error. Zmniejsza to duplikację kodu i czyni lanes czystszymi.

# Haki cyklu życia lanes
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  ensure_git_status_clean
end

after_all do |lane|
  slack(message: "Lane #{lane} zakończony pomyślnie")
end

error do |lane, exception|
  slack(
    message: "Lane #{lane} upadł z błędem: #{exception}",
    success: false
  )
end

lane :deploy do
  match(type: 'appstore')
  gym(export_method: 'app-store')
  deliver
end

Blok error otrzymuje dwa argumenty: nazwę lane (symbol) i obiekt wyjątku. Wewnątrz bloku można wysłać powiadomienie do Slacka, zapisać log do pliku lub uruchomić alternatywny scenariusz odzyskiwania. Jeśli blok error zakończy się pomyślnie, Fastlane nie uznaje kompilacji za nieudaną na poziomie CI/CD.

Private lanes i ponowne użycie

Private lane — to lane zadeklarowany przez private_lane zamiast lane, który nie wyświetla się na liście dostępnych poleceń i nie może być uruchomiony bezpośrednio z terminala. Private lanes są przeznaczone do enkapsulacji powtarzających się kroków, które są wywoływane z kilku publicznych lanes.

Private lanes są szczególnie przydatne dla złożonych sekwencji działań, które muszą być wykonywane w ściśle określonej kolejności. Na przykład private lane :setup_signing może być wywoływany z lanes :build_dev, :build_staging i :build_production z różnymi parametrami, ale sam w sobie nie ma sensu jako osobne polecenie.

# Private lanes do ponownego użycia
private_lane :setup_environment do |options|
  cocoapods(try_repo_update_on_error: true)
  match(type: options[:type], readonly: true)
  increment_build_number
end

lane :dev_build do
  setup_environment(type: 'development')
  gym(export_method: 'development')
end

lane :appstore_build do
  setup_environment(type: 'appstore')
  gym(export_method: 'app-store')
  deliver
end

Private lanes mogą wywoływać inne private lanes, tworząc hierarchię abstrakcji. Zaleca się ograniczenie głębokości zagnieżdżenia do 2–3 poziomów dla zachowania czytelności Fastfile. Dokumentuj każdy private lane komentarzem z opisem jego przeznaczenia i oczekiwanych parametrów.

Przykłady lanes dla iOS i Android

Rozważmy praktyczne przykłady lanes dla projektów iOS i Android. iOS lanes zazwyczaj używają scan do testów, match do certyfikatów, gym do budowania i pilot lub deliver do dostarczania. Android lanes używają gradle do budowania, supply do publikacji i firebase_test_lab do testowania w chmurze.

// Lane dla pełnego CI/CD aplikacji iOS
lane :ci_full_ios do
  scan(scheme: 'App', code_coverage: true)
  gym(scheme: 'App', export_method: 'app-store')
  pilot(distribute_external: true)
  slack(message: 'iOS CI/CD zakończony pomyślnie')
end

/* Lane dla pełnego CI/CD aplikacji Android */
lane :ci_full_android do
  gradle(task: 'testReleaseUnitTest')
  gradle(task: 'bundleRelease')
  supply(track: 'internal')
end

Łącząc lanes dla iOS i Android, można stworzyć jednolity proces CI/CD dla aplikacji wieloplatformowej. Użyj bloków platformowych platform :ios i platform :android do grupowania lanes specyficznych dla platformy i wywołuj je z ogólnego orchestrator lane, który zarządza kolejnością wykonania.

Najlepsze praktyki pisania lanes

Przy pisaniu lanes zaleca się przestrzeganie zestawu praktyk, które zapewniają czytelność, łatwość utrzymania i niezawodność scenariuszy. Pierwsza zasada — każdy lane powinien wykonywać jedno zadanie. Jeśli lane robi zbyt wiele, podziel go na kilka lanes i private lanes.

Druga zasada — nazewnictwo lanes powinno być czasownikiem lub frazą czasownikową: build, deploy, test, upload_screenshots. Unikaj abstrakcyjnych nazw typu process lub do_all. Używaj podkreślników do oddzielania słów w nazwie lane.

Trzecia zasada — obsługuj błędy jawnie. Użyj UI.user_error! do jasnych komunikatów o problemach. Nie polegaj na standardowych komunikatach Fastlane o błędach — podaj deweloperowi kontekst: „Nie znaleziono pliku GoogleService-Info.plist — dodaj go do projektu” zamiast „File not found”.

Czwarta zasada — testuj lanes lokalnie przed uruchomieniem na CI/CD. Fastlane obsługuje tryb dry-run przez flagę --dry-run, który pokazuje, które actions zostaną wykonane, bez faktycznego uruchamiania. Użyj fastlane run_test do izolowanego testowania poszczególnych lanes przed integracją.

Dokumentowanie lanes

Dokumentowanie każdego lane — ważna praktyka w pracy zespołowej. Fastlane obsługuje automatyczne generowanie dokumentacji z bloku desc, umieszczonego przed deklaracją lane. Tekst desc jest wyświetlany przy uruchomieniu fastlane lanes i fastlane list, pomagając deweloperom zrozumieć przeznaczenie każdego scenariusza bez czytania kodu źródłowego Fastfile.

Do dokumentowania parametrów używaj komentarzy Ruby z opisem oczekiwanych wartości. Fastlane może generować plik README.md z pełną listą lanes i ich opisem przez polecenie fastlane generate_docs, co jest wygodne do adaptacji nowych członków zespołu do procesów CI/CD projektu.