CICD Made Easier with Unity CLI

Các quy trình CI/CD có xu hướng phát triển hữu cơ. Những gì bắt đầu như một tập lệnh mở Unity Editor và bắt đầu một bản dựng dần dần đảm nhận nhiều trách nhiệm hơn: tìm tệp thực thi Editor chính xác, cài đặt các mô-đun nền tảng, quản lý giấy phép, thu thập kết quả kiểm tra, xử lý thông tin xác thực ký và dọn dẹp mọi thứ khi công việc hoàn tất.

Kết quả có thể hoạt động, nhưng nó có thể khó hiểu và thậm chí còn khó tái tạo hơn. Đường ống phụ thuộc không chỉ vào mã trong tệp cấu hình của nó, mà còn vào mọi thứ được cài đặt và cấu hình trên trình chạy.

CLI Unity mới cung cấp một cách đơn giản hơn để tự động hóa làm việc với Unity. Nó cung cấp cho các hệ thống xây dựng một lệnh unity nhất quán để cài đặt Trình chỉnh sửa, chạy kiểm thử, tạo bản dựng và quản lý giấy phép. Nó được thiết kế cho các quy trình làm việc bằng terminal và tự động hóa, bao gồm cài đặt không tương tác, đầu ra có cấu trúc và mã thoát rõ ràng. (unity.com)

Điều này không thay thế nhà cung cấp CI của bạn hoặc mã xây dựng của dự án bạn. Thay vào đó, nó giảm bớt máy móc tùy chỉnh cần thiết để kết nối hai thứ đó.

Đơn giản hóa: diễn đạt những gì đường ống cần làm

Trước khi có Unity CLI, hầu hết các pipeline CI đều khởi chạy trực tiếp tệp thực thi Unity Editor. Một lệnh kiểm tra đơn giản có thể trông như thế này:

UNITY_PATH="/opt/unity/editors/6000.2.10f1/Editor/Unity"

"$UNITY_PATH" \
  -batchmode \
  -nographics \
  -quit \
  -projectPath "$PWD" \
  -runTests \
  -testPlatform EditMode \
  -testResults ./results/editmode.xml \
  -logFile -

Không có gì sai về bản chất với cách tiếp cận này. Thử thách là mọi thứ phải xảy ra xung quanh nó.

Đường ống phải biết Trình chỉnh sửa được cài đặt ở đâu. Một tập lệnh hoặc hình ảnh máy khác cần đảm bảo rằng phiên bản được yêu cầu có mặt. Vận động viên cũng phải có các mô-đun nền tảng, cấu hình cấp phép và biến môi trường phù hợp. Các trình chạy Windows, macOS và Linux có thể cần các đường dẫn và logic thiết lập hơi khác nhau.

Lệnh chạy các bài kiểm tra, nhưng quy trình xung quanh nó sở hữu rất nhiều chi tiết triển khai cụ thể của Unity.

Với Unity CLI, cùng một bước có thể được diễn đạt bằng ý định của nó:

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml \
  --allow-install

Điều này yêu cầu pipeline chạy các bài kiểm tra EditMode của dự án và ghi kết quả vào tệp XML NUnit. Với --allow-install, CLI có thể đọc phiên bản Unity mà dự án yêu cầu và cài đặt nó nếu cần. Dự án, thay vì máy xây dựng, trở thành nguồn chân lý về phiên bản Editor nào cần sử dụng.

Các bản dựng tuân theo cùng một quy tắc. Trước đây, một bản dựng có thể gọi trực tiếp Trình chỉnh sửa:

"$UNITY_PATH" \
  -batchmode \
  -nographics \
  -quit \
  -projectPath "$PWD" \
  -buildTarget Android \
  -executeMethod Builder.PerformBuild \
  -logFile -

Với Unity CLI, việc xây dựng dễ đọc hơn:

unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab \
  --allow-install

Phương thức Builder.PerformBuild hiện có của bạn có thể tiếp tục chịu trách nhiệm về các phần của quá trình xây dựng dành riêng cho dự án của bạn: chọn các cảnh, áp dụng cài đặt xây dựng, đặt các ký hiệu kịch bản, gán thông tin phiên bản hoặc chạy xác thực cụ thể của studio.

CLI đơn giản hóa việc tự động hóa xung quanh phương thức đó. Cấu hình CI không còn cần biết nhiều về việc định vị và khởi chạy Trình chỉnh sửa nữa.

Ghép lại, một công việc CI có thể đi từ một runner mới đến một bản dựng đã được kiểm thử với một chuỗi lệnh ngắn:

# Install Unity CLI on macOS and Linux
brew install --cask unity-cli

# Install Unity CLI on Windows
winget install Unity.CLI

# Install a specific Editor and its Android module
unity install 6000.2.10f1 \
  -m android \
  --accept-eula \
  --yes

# Run EditMode tests
unity test . \
  --mode EditMode \
  --output ./results/editmode.xml

# Build an Android App Bundle
unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab

Hoặc, các lệnh kiểm tra và xây dựng có thể sử dụng --allow-install, loại bỏ nhu cầu về bước cài đặt Editor riêng khi dự án nên tự xác định phiên bản.

Sự thay đổi quan trọng không chỉ đơn giản là các lệnh ngắn hơn. Họ truyền đạt những gì công việc đang cố gắng đạt được. Người đọc quy trình có thể thấy Unity được cài đặt ở đâu, các bài kiểm tra chạy ở đâu và bản dựng được tạo ra ở đâu mà không cần phải giải mã một tập hợp các đường dẫn Editor và các cờ chế độ lô.

Vẫn sẽ có những phần khác trong quy trình sản xuất. Nhà cung cấp CI của bạn vẫn kiểm tra kho lưu trữ, tiêm các bí mật, khôi phục bộ nhớ đệm, xuất bản báo cáo kiểm thử và tải lên các tạo phẩm. Unity CLI cung cấp cho các hệ thống đó một cách đơn giản và nhất quán hơn để xử lý các bước cụ thể của Unity.

Cải thiện: loại bỏ rủi ro khỏi quy trình

Một quy trình đơn giản hơn thì dễ đọc và dễ bảo trì hơn, nhưng đơn giản hóa chỉ là một phần của lợi ích. Bằng cách di chuyển việc thiết lập và thực thi Unity ra phía sau một CLI nhất quán, các nhóm cũng có thể giải quyết một số nguồn rủi ro CI/CD phổ biến.

Người chạy có phiên bản Editor sai

Một quy trình phụ thuộc vào một máy được cấu hình sẵn cũng phụ thuộc vào việc máy đó vẫn được cấu hình chính xác. Ai đó có thể cập nhật Trình chỉnh sửa, xóa một mô-đun hoặc thay đổi đường dẫn cài đặt. Một bộ chạy thay thế có thể trông giống hệt nhau trên bảng điều khiển CI nhưng lại khác biệt tinh tế bên trong.

Những khác biệt đó có thể khó nhận thấy. Cấu hình pipeline không thay đổi, và dự án cũng không thay đổi, nhưng quá trình build đột nhiên hoạt động khác đi vì máy đã thay đổi.

Unity CLI cho phép công việc khai báo Editor và các module nó cần:

unity install 6000.2.10f1 \
  -m android \
  --accept-eula \
  --yes

Hoặc công việc có thể sử dụng --allow-install và để ProjectVersion.txt của dự án xác định Trình chỉnh sửa cần thiết.

Điều này biến môi trường xây dựng thành một phần của quy trình thay vì một thuộc tính không được ghi lại của trình chạy. Một nhánh nâng cấp Unity có thể mang yêu cầu đó vào CI cùng với nó thay vì chờ kỹ sư xây dựng cập nhật mọi ảnh chạy.

Nó cũng làm cho các runner tạm thời trở nên thực tế hơn. Một người chạy mới không cần phải bắt đầu cuộc đời như một cỗ máy xây dựng Unity được chuẩn bị kỹ lưỡng. Nó có thể cài đặt CLI và cung cấp môi trường cần thiết như một phần của công việc.

CI hoạt động khác với máy của nhà phát triển

Các tập lệnh dành riêng cho nhà cung cấp có thể tạo ra khoảng cách giữa phát triển cục bộ và CI. Khi một tác vụ thất bại, nhà phát triển có thể nhận được một lệnh Editor lớn chứa các đường dẫn và tùy chọn mà chỉ có ý nghĩa trên trình chạy bản dựng.

Tái tạo lỗi đó cục bộ đòi hỏi phải dịch tập lệnh CI thành thứ gì đó hoạt động trên máy của nhà phát triển.

Unity CLI thu hẹp khoảng cách đó vì cùng một lệnh có thể được sử dụng ở cả hai nơi:

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml \
  --allow-install

Môi trường CI vẫn sẽ có những khác biệt—chẳng hạn như bí mật, cấp phép và xuất bản artifact—nhưng điểm vào hướng tới Unity vẫn giữ nguyên.

Điều đó giúp việc điều tra một công việc thất bại dễ dàng hơn. Một nhà phát triển có thể sao chép lệnh kiểm tra hoặc xây dựng, chạy nó từ thư mục dự án và bắt đầu tái tạo sự cố mà không cần tái tạo lời gọi Editor của trình chạy trước.

Các tập lệnh tổng quát tùy chỉnh trở thành cơ sở hạ tầng của riêng chúng

Nhiều studio có các script để định vị các cài đặt Unity, dịch các mục tiêu build thành các đối số Editor, truyền luồng nhật ký, diễn giải mã thoát và di chuyển kết quả kiểm thử vào thư mục thích hợp.

Những kịch bản này thường được tạo ra vì những lý do chính đáng. Tuy nhiên, theo thời gian, chúng trở thành một lớp cơ sở hạ tầng khác cần được kiểm tra và bảo trì. Chúng cũng có thể bị trùng lặp giữa các dự án hoặc được viết lại cho từng nhà cung cấp CI.

Unity CLI cung cấp một điểm vào duy nhất cho các hoạt động chung:

unity install
unity test
unity build

Điều này không có nghĩa là mọi dự án đều trở nên giống hệt nhau. Các studio có thể—và nên—giữ logic cụ thể của dự án ở nơi nó thuộc về. Một phương thức build C# có thể tiếp tục xác định cách một trò chơi được xây dựng, trong khi CLI cung cấp một cách tiêu chuẩn để tự động hóa gọi nó.

Ranh giới trở nên rõ ràng hơn: dự án sở hữu bản dựng, trong khi công việc CI sở hữu khi nào và ở đâu bản dựng đó chạy.

Các lỗi khó chẩn đoán

Một công việc Unity thất bại có thể tạo ra một lượng lớn đầu ra. Nếu kết quả kiểm tra chỉ tồn tại trong nhật ký Trình chỉnh sửa, các nhà phát triển có thể cần tải xuống và tìm kiếm nhật ký đó để tìm lỗi thực tế. Trên một runner tạm thời, các tệp chẩn đoán hữu ích cũng có thể biến mất ngay khi công việc hoàn thành.

unity test có thể viết báo cáo XML NUnit trực tiếp:

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml

Các nhà cung cấp CI có thể nhập báo cáo đó và hiển thị nó. Nó cũng sử dụng các mã thoát được xác định và duy trì các nhật ký cụ thể của CLI, giúp tự động hóa phân biệt các lỗi kiểm tra với các sự cố khác. (docs.unity.com)

Kết quả không chỉ đơn thuần là nhiều nhật ký hơn. Nó hữu ích hơn khi xuất ra ở những nơi mà các nhà phát triển đã xem: nhật ký công việc, báo cáo kiểm thử và các tạo phẩm xây dựng.

Một quy trình có thể lưu giữ các kết quả đầu ra chính từ mỗi lần chạy:

results/editmode.xml
results/playmode.xml
out/app.aab
Editor.log
cli-log.json

Điều này giúp việc vận hành quy trình dễ dàng hơn ở quy mô lớn. Các nhà phát triển có thể tự mình điều tra các lỗi kiểm thử thông thường, trong khi các kỹ sư xây dựng giữ lại các nhật ký chi tiết cần thiết để chẩn đoán các sự cố cơ sở hạ tầng.

Thông tin xác thực và giấy phép tồn tại lâu hơn công việc

Các trình chạy thường cần truy cập vào các tài liệu nhạy cảm: thông tin xác thực tài khoản dịch vụ, kho khóa Android, mật khẩu ký hoặc tệp giấy phép ngoại tuyến. Các máy có tuổi thọ cao có thể giữ lại các tệp hoặc thay đổi môi trường đó giữa các lần xây dựng trừ khi quy trình thực hiện việc dọn dẹp cẩn thận.

Quy trình làm việc ưu tiên CLI phù hợp tự nhiên với các kho bí mật và các trình chạy tạm thời. Thông tin xác thực có thể được tiêm dưới dạng biến môi trường, được công việc sử dụng và bị loại bỏ khi trình chạy bị xóa.

Việc ký tệp có thể tuân theo cùng một mẫu. Ví dụ, một keystore Android có thể được lưu trữ dưới dạng bí mật CI được mã hóa base64, chỉ được giải mã trong quá trình xây dựng và bị xóa trong quá trình dọn dẹp:

echo "$ANDROID_KEYSTORE_BASE64" \
  | base64 --decode > ./android.keystore

unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab

rm -f ./android.keystore

Giấy phép cũng có thể trở thành một phần rõ ràng của vòng đời công việc. Người chạy kích hoạt giấy phép trước khi thực hiện công việc Unity và trả lại nó khi công việc kết thúc:

unity license activate --floating

# Run tests and produce builds

unity license return

Unity CLI hỗ trợ các quy trình kích hoạt và trả về, bao gồm các tùy chọn cấp phép nổi và ngoại tuyến. (docs.unity.com)

Đối với các runner tạm thời, lệnh trả về nên được đặt trong bước dọn dẹp vô điều kiện để nó chạy ngay cả khi bài kiểm tra hoặc bản dựng thất bại. Điều đó ngăn các công việc thất bại rời khỏi các chỗ đã được kiểm tra và ảnh hưởng đến các bản dựng sau này.

Đường ống được liên kết với một nhà cung cấp CI

Mỗi nền tảng CI đều có ngôn ngữ cấu hình riêng, nhưng công việc Unity bên trong job không nên thay đổi khi nhà cung cấp thay đổi.

Một pipeline có thể sử dụng GitHub Actions, GitLab CI, Jenkins, Buildkite, TeamCity hoặc một hệ thống điều phối nội bộ. Các hệ thống đó sẽ tiếp tục quản lý việc lập lịch, bí mật, bộ nhớ đệm và các tạo phẩm. Các lệnh kiểm tra và xây dựng dự án Unity có thể giữ nguyên:

unity test . --mode EditMode --output ./results/editmode.xml
unity build . --target Android --output-path ./out/app.aab

Điều này không làm cho việc di chuyển CI trở nên dễ dàng, nhưng nó giảm lượng tự động hóa cụ thể của Unity cần phải viết lại. Nhà cung cấp chạy lệnh; Unity CLI xử lý tương tác với Unity.

Sự nhất quán đó cũng hữu ích trên các dự án. Các nhóm xây dựng có thể thiết lập các mẫu đường ống chung mà không yêu cầu mọi dự án phải chia sẻ cùng một triển khai xây dựng nội bộ.

Cuối cùng, Unity CLI không thay đổi những gì một quy trình CI/CD tốt cần thực hiện. Đường ống vẫn phải cấp phát môi trường, chạy kiểm thử, tạo bản dựng, bảo vệ thông tin xác thực, xuất bản kết quả hữu ích và tự dọn dẹp.

Những thay đổi là cần bao nhiêu máy móc tùy chỉnh để làm cho các bước đó hoạt động với Unity.

Thay vì dựa vào các đường dẫn Editor được mã hóa cứng, các trình chạy được cấu hình sẵn và các tập lệnh tổng quát ngày càng phức tạp, các nhóm có thể mô tả ý định của họ bằng một tập hợp nhỏ các lệnh. Kết quả là một quy trình dễ đọc hơn, dễ tái tạo hơn và ít phụ thuộc vào trạng thái của một máy xây dựng cụ thể hơn.

Sử dụng Unity CLI để đơn giản hóa đường dẫn từ một trình chạy sạch đến một bản dựng đã được kiểm thử—và cải thiện độ tin cậy của mọi thứ trên đường đi.