Fastfile: bản chất, cấu trúc và thiết lập tự động hóa trong phát triển di động

Fastfile là gì và tại sao cần nó

Fastfile là tệp cấu hình chính của Fastlane, viết bằng Ruby và đặt trong thư mục fastlane ở thư mục gốc của dự án. Nó xác định tất cả các kịch bản tự động hóa (lanes) cho việc build, kiểm thử, ký mã và phân phối ứng dụng. Fastfile thay thế hàng chục script bash, Makefile và hướng dẫn thủ công bằng một mô tả khai báo CI/CD pipeline thống nhất.

Sự cần thiết của Fastfile xuất hiện khi dự án yêu cầu các bản build có thể lặp lại trên các máy khác nhau của nhà phát triển và máy chủ CI/CD. Thay vì mỗi nhà phát triển tự cấu hình môi trường thủ công, Fastfile ghi lại tất cả các bước trong mã nguồn, có thể quản lý phiên bản trong Git, được review và tái sử dụng giữa các dự án. Một Fastfile duy nhất đảm bảo rằng bản build trên máy nhà phát triển giống hệt bản build trên máy chủ CI/CD.

Fastfile hỗ trợ nền tảng thông qua chỉ thị default_platform. Trong một Fastfile có thể mô tả các kịch bản cho iOS, Android và macOS, nhóm chúng trong các khối platform :ios và platform :android. Điều này đặc biệt thuận tiện cho các dự án đa nền tảng, nơi iOS và Android có chung logic triển khai nhưng công cụ build khác nhau.

Cấu trúc Fastfile: lanes, actions và tham số

Fastfile gồm ba thành phần chính: khai báo nền tảng (default_platform), định nghĩa lanes và cấu hình các hàm hỗ trợ. Mỗi lane bắt đầu bằng từ khóa lane, theo sau là tên kịch bản (symbol Ruby), thân với chuỗi actions và các khối xử lý lỗi error, success hoặc ensure.

Actions trong Fastfile là các lời gọi hàm tích hợp của Fastlane với tham số dạng Hash. Ví dụ: gym(scheme: 'App', export_method: 'app-store') chạy build ứng dụng iOS với các tham số đã chỉ định. Mỗi action trả về kết quả có thể lưu vào biến và sử dụng trong các action tiếp theo — điều này cho phép xây dựng logic điều kiện bên trong lane.

Fastfile hỗ trợ biến môi trường thông qua cơ chế ENV tiêu chuẩn trong Ruby. Dữ liệu nhạy cảm (mật khẩu, token, khóa) không nên lưu trong Fastfile — hãy sử dụng biến môi trường của hệ thống CI/CD hoặc tệp .env đã được thêm vào .gitignore. Fastlane tự động tải các tệp .env từ thư mục fastlane khi khởi chạy.

Appfile và Matchfile

Cùng với Fastfile trong thư mục fastlane còn có các tệp cấu hình bổ sung. Appfile chứa mã định danh ứng dụng (app_identifier), Apple ID và Team ID — dữ liệu này tự động được điền vào tất cả các action, giúp tránh lặp lại trong mỗi lane. Matchfile lưu cấu hình cho match: URL kho Git, loại hồ sơ và khóa mã hóa.

Việc chia tách cấu hình thành nhiều tệp giúp đơn giản hóa việc duy trì các dự án với nhiều môi trường khác nhau. Ví dụ: cho staging và production có thể tạo các nhánh riêng trong kho Matchfile hoặc ghi đè tham số qua biến môi trường trong hệ thống CI/CD.

# Cấu trúc cơ bản của Fastfile
default_platform(:ios)

lane :build_and_test do
  cocoapods
  scan(scheme: 'App', devices: ['iPhone 15'])
  gym(scheme: 'App')
end

lane :deploy do
  match(type: 'appstore')
  build_and_test
  pilot(skip_waiting_for_build_processing: true)
end

Cú pháp Fastfile: viết lanes

Cú pháp Fastfile dựa trên Ruby DSL (Domain Specific Language), được thiết kế đặc biệt để dễ đọc các kịch bản tự động hóa. Lane được khai báo qua cấu trúc lane :name do ... end, trong đó name là symbol Ruby trở thành lệnh fastlane name để chạy từ terminal hoặc hệ thống CI/CD.

Bên trong lane có thể sử dụng toán tử điều kiện Ruby: if, unless, case để rẽ nhánh logic. Ngoài ra còn có vòng lặp each và while để xử lý mảng giá trị. Fastlane cung cấp các phương thức đặc biệt before_all, after_all và error block để xử lý các sự kiện trong vòng đời của lane.

Tham số lane được truyền qua options hash. Khi chạy fastlane build --option_name value, giá trị sẽ vào options[:option_name] bên trong lane. Có thể đặt giá trị mặc định qua optional: true và xác thực kiểu dữ liệu để kiểm soát các tham số truyền vào.

# Lane với tham số và logic điều kiện
lane :build do |options|
  scheme = options[:scheme] || 'App'
  export_method = options[:export_method] || 'development'

  match(type: export_method)

  if export_method == 'appstore'
    gym(scheme: scheme, export_method: 'app-store')
    pilot(skip_waiting_for_build_processing: true)
  else
    gym(scheme: scheme, export_method: export_method)
  end
end

Ví dụ Fastfile cho iOS

Fastfile đầy đủ cho dự án iOS bao gồm các lanes để cài đặt phụ thuộc, kiểm thử, build và triển khai lên TestFlight và App Store. Hãy xem xét ví dụ bao quát quy trình CI/CD điển hình từ commit đến phát hành trên TestFlight cho kiểm thử nội bộ.

# Fastfile cho CI/CD iOS
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  setup_travis if ENV['TRAVIS']
end

lane :tests do
  scan(
    scheme: 'App',
    devices: ['iPhone 15', 'iPad Pro 12.9'],
    output_directory: './test_reports'
  )
end

lane :build_appstore do
  match(type: 'appstore', readonly: true)
  gym(
    scheme: 'App',
    export_method: 'app-store',
    include_bitcode: true
  )
end

lane :deploy_testflight do
  build_appstore
  pilot(
    skip_waiting_for_build_processing: true,
    distribute_external: false
  )
  slack(
    message: 'Bản build đã được tải lên TestFlight để kiểm thử nội bộ'
  )
end

Trong ví dụ này, khối before_all được thực thi trước mỗi lane và cài đặt các phụ thuộc. Lane tests chạy kiểm thử UI và Unit trên hai thiết bị. Lane build_appstore ký mã qua match và tạo IPA với bitcode. Lane deploy_testflight kết hợp tất cả các bước để phân phối hoàn chỉnh.

Triển khai với nhiều target

Các dự án với nhiều target (ứng dụng chính, watchOS, widget, Notification Service Extension) yêu cầu các lanes riêng cho từng target. Trong Fastfile có thể tạo lane :deploy_target chung, nhận tên scheme và đường dẫn build làm tham số. Điều này cho phép chạy triển khai cho tất cả extension qua fastlane deploy_target scheme:Widget.

Để tổ chức nhiều target, hãy sử dụng mảng scheme và vòng lặp each bên trong lane. Fastlane hỗ trợ build song song nhiều scheme qua cờ parallel: true, giúp giảm tổng thời gian pipeline CI/CD cho ứng dụng có extension.

Ví dụ Fastfile cho Android

Fastfile cho dự án Android sử dụng gradle action để chạy tác vụ Gradle và supply action để phát hành lên Google Play. Khác với iOS, Android không yêu cầu match nhưng sử dụng Keystore để ký, được lưu bên ngoài kho và truyền qua biến môi trường.

# Fastfile cho CI/CD Android
default_platform(:android)

lane :build_release do
  gradle(task: 'clean')
  gradle(task: 'bundleRelease')
  gradle(task: 'assembleRelease')
end

lane :deploy_internal do
  build_release
  supply(
    track: 'internal',
    aab: 'app/build/outputs/bundle/release/app-release.aab',
    release_status: 'completed'
  )
end

Để ký Android ứng dụng, hãy cấu hình signingConfigs trong build.gradle và truyền tham số Keystore qua biến môi trường: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS và ANDROID_KEY_PASSWORD. Fastlane tự động sử dụng apksigner hệ thống để ký AAB hoặc APK đã build.

Ký Android trong Fastfile

Để cấu hình ký Android trong Fastfile, hãy sử dụng action sign_android hoặc dựa vào signingConfigs trong build.gradle. Fastlane tích hợp với apksigner qua Gradle — truyền cờ SIGNING_CONFIG vào gradle task sẽ kích hoạt ký với tham số từ biến môi trường. Điều này cho phép ký tệp AAB trước khi tải lên Google Play Console.

Để lưu trữ Keystore an toàn trong CI/CD, hãy sử dụng mã hóa Base64 và biến môi trường. Fastlane hỗ trợ action setup_keystore, giải mã Keystore từ biến và lưu vào tệp tạm thời ở giai đoạn before_all. Sau khi lane hoàn thành, tệp tạm thời tự động bị xóa để ngăn rò rỉ chứng chỉ.

Sử dụng private lanes và nhóm

Private lanes (kịch bản riêng tư) là các lanes không thể gọi trực tiếp từ dòng lệnh nhưng có thể được gọi từ các lanes khác trong Fastfile. Private lane được khai báo qua cấu trúc private_lane :name do ... end và được sử dụng để đóng gói các bước lặp lại không có ý nghĩa như các kịch bản độc lập.

Private lanes lý tưởng cho nhóm logic lặp lại: cài đặt phụ thuộc, cấu hình môi trường, gửi thông báo. Ví dụ: có thể tạo private lane :setup_signing được gọi từ nhiều lane triển khai nhưng không nên cho phép chạy trực tiếp bởi nhà phát triển để tránh lỗi.

# Private lane và nhóm
default_platform(:ios)

private_lane :setup_signing do |options|
  match(
    type: options[:type],
    readonly: true,
    verbose: false
  )
end

lane :beta do
  setup_signing(type: 'adhoc')
  gym(export_method: 'ad-hoc')
  pilot(distribute_external: true)
end

lane :release do
  setup_signing(type: 'appstore')
  gym(export_method: 'app-store')
  deliver(
    force: true,
    submit_for_review: true
  )
end

Nhóm lanes qua khối platform cho phép tách biệt các kịch bản cho iOS và Android trong một Fastfile. Cấu trúc platform :ios do ... end và platform :android do ... end cô lập lanes của nền tảng tương ứng, còn các private lanes chung có thể đặt bên ngoài khối nền tảng để tái sử dụng.

Truyền tham số vào lanes

Cơ chế tham số của Fastfile cho phép làm cho lanes linh hoạt và có thể tái sử dụng. Tham số được truyền khi chạy qua dòng lệnh: fastlane build scheme:App export_method:appstore. Bên trong lane, giá trị có thể truy cập qua options hash được truyền vào khối lane như một đối số.

Fastlane hỗ trợ tham số có kiểu dữ liệu với xác thực qua OptionalHash. Có thể đặt kiểu giá trị (String, Boolean, Integer), giá trị mặc định và mô tả để tự động tạo tài liệu. Ngoài ra còn có biến môi trường như cách thay thế để truyền tham số, thuận tiện cho hệ thống CI/CD.

# Tham số với xác thực kiểu dữ liệu
lane :build do |options|
  gym(
    scheme: options[:scheme],
    export_method: options[:export_method] || 'development',
    include_bitcode: options[:include_bitcode] || false,
    output_name: options[:output_name]
  )
  slack(message: "Xây dựng #{options[:scheme]} đã hoàn tất")
end

# Lệnh chạy: fastlane build scheme:MyApp export_method:appstore

Nên sử dụng giá trị mặc định cho tất cả tham số không bắt buộc để lane có thể chạy mà không cần chỉ định từng đối số. Đối với tham số bắt buộc, hãy kiểm tra giá trị ở đầu lane và dừng thực thi với thông báo lỗi rõ ràng qua UI.user_error!.