Match (Fastlane): quản lý chứng chỉ và thiết lập trong phát triển iOS

Match (Fastlane) là gì?

Match (Fastlane) là một thành phần của hệ sinh thái Fastlane, được thiết kế để quản lý tập trung chứng chỉ Code Signing và Provisioning Profiles cho phát triển iOS. Nó giải quyết vấn đề đồng bộ chữ ký giữa các thành viên trong nhóm và tự động hóa thiết lập chứng chỉ trong pipeline CI/CD mà không cần sự can thiệp của nhà phát triển.

Không có Match, mỗi thành viên trong nhóm phải tự tạo chứng chỉ thủ công qua Xcode hoặc Apple Developer Portal, dẫn đến xung đột khi build trên các máy khác nhau. Code Signing là quá trình ký số ứng dụng iOS, xác nhận quyền tác giả và tính toàn vẹn của ứng dụng trước khi cài đặt trên thiết bị người dùng.

Theo Tài liệu Apple Developer (2025), cấu hình chứng chỉ không đúng là một trong những nguyên nhân phổ biến nhất gây từ chối khi gửi ứng dụng lên App Store. Match tự động kiểm tra tính hợp lệ của chứng chỉ và cảnh báo về ngày hết hạn, giảm nguy cơ build bị từ chối ở giai đoạn xác minh của Apple.

Sử dụng Match trong bất kỳ dự án nào có từ hai nhà phát triển trở lên hoặc có pipeline CI/CD — điều này giảm thời gian thiết lập môi trường cho thành viên mới từ 30 phút xuống còn một lệnh trong terminal.

Match hoạt động như thế nào: kho Git được mã hóa

Kiến trúc Match được xây dựng dựa trên khái niệm một nguồn sự thật duy nhất cho tất cả chứng chỉ của nhóm iOS. Thay vì lưu trữ cục bộ trong keychain của từng nhà phát triển, Match tập hợp các chứng chỉ vào một kho Git duy nhất với mã hóa từng tệp trước khi lưu.

Quy trình gồm ba giai đoạn. Ở giai đoạn khởi tạo, Match tạo tất cả chứng chỉ và hồ sơ cần thiết qua API Apple Developer Portal. Mỗi tệp được mã hóa bằng thuật toán AES-256 với khóa được tạo từ cụm mật khẩu người dùng. Các tệp đã mã hóa được lưu vào kho Git và đồng bộ với máy chủ từ xa qua các thao tác Git tiêu chuẩn push và pull.

Kiến trúc mã hóa chứng chỉ

Match sử dụng kết hợp OpenSSL và cụm mật khẩu người dùng để mã hóa chứng chỉ và hồ sơ. Khóa truy cập được đặt qua biến môi trường MATCH_PASSWORD và không được lưu trong kho, loại trừ rò rỉ ngay cả khi máy chủ Git bị xâm phạm hoặc kho có quyền truy cập công cộng.

Khi yêu cầu chứng chỉ, Match tải tệp đã mã hóa từ kho, giải mã cục bộ bằng cụm mật khẩu và cài đặt vào Keychain của máy hiện tại. Sau khi build hoàn tất, chứng chỉ có thể bị xóa khỏi Keychain để tuân thủ chính sách bảo mật của môi trường doanh nghiệp, ngăn chặn việc sử dụng chứng chỉ lỗi thời trong các bản build sau.

Mỗi chứng chỉ được lưu với tên chứa mã định danh ứng dụng, loại hồ sơ và ngày tạo. Cấu trúc này cho phép Match quản lý phiên bản chứng chỉ và nếu cần, có thể khôi phục trạng thái trước đó qua các lệnh Git tiêu chuẩn revert và reset. Điều này đặc biệt hữu ích khi vô tình xóa hoặc ghi đè hồ sơ.

Thiết lập và cấu hình Match

Cài đặt Match được thực hiện cùng với Fastlane qua trình quản lý gói Ruby: gem install fastlane. Sau khi cài đặt, khởi tạo kho chứng chỉ bằng lệnh fastlane match init, lệnh này tạo một kho Git trống và tạo tệp Matchfile với mẫu cấu hình cơ bản.

# Khởi tạo kho Match
fastlane match init

Cấu hình qua Matchfile

Tệp Matchfile chứa tất cả tham số kết nối đến kho chứng chỉ: URL kho Git, loại hồ sơ mặc định, mã định danh ứng dụng và thông tin xác thực Apple Developer. Ví dụ cấu hình điển hình cho nhóm năm nhà phát triển:

# Matchfile configuration
git_url("https://github.com/company/certificates.git")
type(:development)
app_identifier(["com.company.app", "com.company.app.extension"])
username("developer@company.com")
team_id("TEAM123456")
git_branch("main")

Tham số type xác định loại hồ sơ: :development để gỡ lỗi trên thiết bị nhà phát triển, :appstore để xuất bản lên App Store, :adhoc để thử nghiệm trên thiết bị bên ngoài và :enterprise để phân phối nội bộ In-House ngoài App Store. Mỗi loại tạo một thư mục riêng trong kho, cho phép tổ chức hồ sơ theo kịch bản build mục tiêu.

Match hỗ trợ nhiều phương thức xác thực trên Apple Developer Portal: xác thực hai yếu tố qua Apple ID, Mật khẩu riêng cho ứng dụng (App-Specific Password) và khóa API App Store Connect. Đối với CI/CD, nên sử dụng khóa API — chúng không yêu cầu nhập mã xác nhận tương tác và không chặn build tự động khi thay đổi thiết bị nhà phát triển.

Tạo và đồng bộ hồ sơ

Sau khi cấu hình Matchfile, thực thi lệnh fastlane match development hoặc fastlane match appstore để tạo và đồng bộ hồ sơ. Match tự động tạo hoặc cập nhật chứng chỉ qua API Apple Developer Portal và lưu chúng vào kho. Apple Developer Portal là giao diện web của Apple để quản lý chứng chỉ, mã định danh ứng dụng và danh sách thiết bị nhà phát triển được phép.

Ở lần chạy đầu tiên, Match yêu cầu cụm mật khẩu để mã hóa kho. Cụm mật khẩu này phải được lưu trong trình quản lý bí mật CI/CD (GitHub Actions Secrets, GitLab CI Variables hoặc Jenkins Credentials) và truyền qua biến môi trường MATCH_PASSWORD. Nếu không có nó, Match không thể giải mã chứng chỉ trên các máy khác hoặc trong môi trường CI.

Lệnh Match chính để quản lý chứng chỉ

Giao diện Match bao gồm một tập hợp các lệnh để tạo, cập nhật, đồng bộ và xóa chứng chỉ cùng hồ sơ. Mỗi lệnh tương ứng với một hành động cụ thể trong vòng đời Code Signing, từ tạo mới đến dọn dẹp hoàn toàn kho.

Lệnh cho công việc hàng ngày

Lệnh fastlane match development tải xuống hoặc tạo chứng chỉ và hồ sơ Development để gỡ lỗi trên thiết bị cục bộ. Provisioning Profile là tài liệu kỹ thuật số của Apple kết nối chứng chỉ nhà phát triển với mã định danh ứng dụng và danh sách thiết bị được phép cài đặt.

Để xuất bản lên App Store, sử dụng fastlane match appstore — lệnh này tạo chứng chỉ Distribution và hồ sơ AppStore. Lệnh fastlane match adhoc tạo hồ sơ cho thử nghiệm trên thiết bị bên ngoài, và fastlane match enterprise cho ứng dụng doanh nghiệp In-House.

# Tạo hồ sơ Development để gỡ lỗi
fastlane match development

# Tạo hồ sơ AppStore cho bản phát hành
fastlane match appstore

# Nhập chứng chỉ thủ công hiện có
fastlane match import

Lệnh fastlane match import cho phép thêm chứng chỉ hiện có vào kho — hữu ích khi di chuyển từ quản lý thủ công sang Match. Tham số --readonly chặn mọi thay đổi trong kho, rất quan trọng cho môi trường CI nơi pipeline không được phép tự động tạo hoặc xóa chứng chỉ và hồ sơ.

Để dọn dẹp hoàn toàn kho, sử dụng lệnh fastlane match nuke. Lệnh này xóa tất cả chứng chỉ khỏi kho Git, Apple Developer Portal và máy cục bộ — đây là thiết lập lại hoàn toàn trạng thái Code Signing cho dự án. Lệnh chỉ được sử dụng khi có xung đột nghiêm trọng hoặc khi chuyển sang tài khoản Apple Developer mới.

Tích hợp Match vào pipeline CI/CD

Tích hợp CI/CD là một trong những lợi thế chính của Match. Trong pipeline GitHub Actions, GitLab CI, Bitrise hoặc Jenkins, Match tự động tải xuống và cài đặt chứng chỉ chính xác mà không cần nhà phát triển can thiệp. Điều này cho phép thực hiện build và ký hoàn toàn tự động cho ứng dụng iOS, từ commit đến IPA hoàn chỉnh.

Cấu hình điển hình cho GitHub Actions bao gồm cài đặt Fastlane, thiết lập biến MATCH_PASSWORD và chạy Match với cờ --readonly. GitHub Actions là nền tảng CI/CD của GitHub tự động hóa việc build, kiểm thử và xuất bản mã dựa trên các sự kiện trong kho.

# Cài đặt Fastlane trong môi trường CI
gem install fastlane --no-document

# Chạy Match ở chế độ chỉ đọc không có quyền thay đổi
fastlane match development --readonly

Trước khi chạy Match trong CI, cần thiết lập quyền truy cập vào kho chứng chỉ. Fastlane tự động sao chép kho dựa trên tham số git_url từ Matchfile. Quyền truy cập kho được cấu hình qua khóa SSH hoặc personal access token được thêm vào bí mật của hệ thống CI — điều này đảm bảo chứng chỉ không bị xâm phạm qua truy cập công khai.

Thiết lập các biến môi trường MATCH_PASSWORD và FASTLANE_APPLE_API_KEY trong bí mật của nhà cung cấp CI của bạn. Khóa API App Store Connect cho phép Match xác thực trên Apple Developer Portal mà không cần xác thực hai yếu tố, loại bỏ các yêu cầu tương tác trong build tự động và ngăn chặn pipeline bị chặn.

Lỗi thường gặp khi làm việc với Match

Ngay cả khi cấu hình Match đúng, vẫn có thể xảy ra lỗi liên quan đến hết hạn chứng chỉ, xung đột hồ sơ hoặc cấu hình môi trường không chính xác. Chẩn đoán sự cố Match dựa trên phân tích nhật ký lệnh và kiểm tra trạng thái mới nhất của kho Git chứng chỉ.

Lỗi phổ biến nhất “You need to provide a password for Match” xảy ra khi biến môi trường MATCH_PASSWORD chưa được đặt trên máy hoặc trong môi trường CI. Giải pháp: thêm MATCH_PASSWORD vào biến môi trường hệ thống hoặc truyền mật khẩu qua tham số --keychain_password khi chạy lệnh Match.

Vấn đề phổ biến thứ hai là xung đột chứng chỉ khi thêm thiết bị mới vào hồ sơ AdHoc. Giải pháp bằng lệnh fastlane match adhoc --force, lệnh này tạo lại hồ sơ với các thiết bị mới. Chứng chỉ Apple Developer có hiệu lực một năm, sau đó build sử dụng chúng sẽ bị App Store Connect từ chối. Match cảnh báo về việc hết hạn 30 ngày trước thời hạn.

Khi gặp lỗi “Multiple matches found for...”, trong kho có nhiều phiên bản của cùng một chứng chỉ. Sử dụng lệnh fastlane match nuke để dọn dẹp hoàn toàn kho và xóa tất cả chứng chỉ khỏi Apple Developer Portal. Sau khi dọn dẹp, thực hiện tạo lại từ đầu — điều này đảm bảo trạng thái hồ sơ nhất quán không có trùng lặp hoặc phiên bản xung đột.