Giới Thiệu
Chào mừng các bạn đến với hướng dẫn siêu chi tiết về cách publish một thư viện Kotlin Multiplatform lên GitHub Packages. Nếu bạn đã từng cảm thấy bối rối với việc này, thì đừng lo, chúng ta sẽ cùng nhau vượt qua mọi khó khăn!
Bước 1: Thêm Plugin maven-publish
Đầu tiên, chúng ta cần thêm plugin maven-publish vào file build.gradle.kts của module mà bạn muốn publish. Đoạn code này giống như việc thêm một chút gia vị vào món ăn của bạn, giúp nó trở nên hoàn hảo hơn.
plugins { ... id("maven-publish")
}
Bước 2: Cấu Hình publishing Trong build.gradle.kts
Tiếp theo, chúng ta sẽ thêm đoạn code dưới đây vào file build.gradle.kts vừa thêm plugin. Đoạn code này giống như việc chuẩn bị nguyên liệu cho món ăn của bạn, đảm bảo mọi thứ đều sẵn sàng.
publishing { repositories { maven { url = uri("<package-url>") credentials { username = findProperty("gpr.user") as String? ?: System.getenv("USERNAME_GITHUB") password = findProperty("gpr.token") as String? ?: System.getenv("TOKEN_GITHUB") } } } publications.withType<MavenPublication>().forEach { publication -> val targetName = publication.name.substringAfterLast(":") val artifactId = if (targetName == "kotlinMultiplatform") { "\"<artifact-id>\"" } else { "<artifact-id>-$targetName".lowercase() } publication.groupId = "<group-id>" publication.artifactId = artifactId publication.pom { name.set(rootProject.name) description.set(findProperty("publicationDescriptionLibrary") as String) url.set(findProperty("publicationUrl") as String) licenses { license { name.set(findProperty("publicationLicenseName") as String) url.set(findProperty("publicationLicenseUrl") as String) } } scm { url.set(findProperty("publicationScmUrl") as String) connection.set(findProperty("publicationScmConnection") as String) developerConnection.set(findProperty("publicationScmDeveloperConnection") as String) } developers { developer { id.set(findProperty("publicationDeveloperId") as String) name.set(findProperty("publicationDeveloperName") as String) } } } }
}
Giải Thích Chi Tiết
repositories { maven { ... } }: Đây là nơi chúng ta định nghĩa repository mà chúng ta sẽ publish thư viện của mình. URL và thông tin đăng nhập được lấy từ các biến môi trường hoặc các thuộc tính được định nghĩa trong project.- Thông thường
urlsẽ có dạng:https://maven.pkg.github.com/<github-user>/<repo-name>
- Thông thường
publications.withType<MavenPublication>().forEach { ... }: Chúng ta duyệt qua tất cả các publication và cấu hình chúng.publication.groupId,publication.artifactId: Đặt groupId và artifactId cho publication.artifactIdcho các target sẽ có dạng<artifact>cho common, và<artifact>-android,<artifact>-iosx64,<artifact>-js,<artifact>-jvmcho các target khác của module.
publication.pom { ... }: Cấu hình POM (Project Object Model) cho publication, bao gồm tên, mô tả, URL, license, SCM (Source Control Management), và thông tin developer.
Bước 3: Viết File publish.yml Để Publish Lên GitHub Packages
Cuối cùng, chúng ta sẽ viết file publish.yml để sử dụng GitHub Actions publish thư viện của chúng ta lên GitHub Packages. Đây là bước cuối cùng, giống như việc nấu chín món ăn và dọn ra bàn.
name: Publish Package on: push: tags: [ 'v*' ] env: JAVA_VERSION: '17' GRADLE_CACHE_PATH: | ~/.gradle/caches ~/.gradle/wrapper USERNAME_GITHUB: ${{ github.actor }} TOKEN_GITHUB: ${{ secrets.GITHUB_TOKEN }} jobs: publish: name: Publish Package runs-on: macos-latest permissions: contents: read packages: write steps: - uses: actions/checkout@v4 - name: Cache Gradle packages uses: actions/cache@v3 with: path: ${{ env.GRADLE_CACHE_PATH }} key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }} restore-keys: ${{ runner.os }}-gradle- - name: Setup Java uses: actions/setup-java@v4 with: java-version: ${{ env.JAVA_VERSION }} distribution: 'temurin' cache: gradle - name: Grant execute permission for gradlew run: chmod +x gradlew - name: Publish package run: ./gradlew publish
Giải Thích Chi Tiết
on: push: tags: [ 'v*' ]: Kích hoạt workflow khi có tag mới bắt đầu bằng v.env: Định nghĩa các biến môi trường như phiên bản Java, đường dẫn cache của Gradle, và thông tin đăng nhập GitHub.jobs: Định nghĩa các job trong workflow.publish: Job này sẽ publish package lên GitHub Packages nếu có tag mới bắt đầu bằngv.
Release Process
Đây là quy trình phát hành phiên bản mới của dự án. Quy trình này bán tự động, dựa vào cả các bước thủ công và các pipeline CI/CD tự động.
Các Bước Phát Hành
- Tạo Nhánh Phát Hành: Bắt đầu bằng việc tạo một nhánh mới từ main (hoặc nhánh mặc định của bạn) có tên là releases/vX.X.X, trong đó X.X.X là số phiên bản mới.
git checkout main
git pull origin main
git checkout -b releases/vX.X.X
- Cập Nhật Phiên Bản và Changelog: Cập nhật số phiên bản trong các thư viện của dự án và file
CHANGELOG.mdđể phản ánh phiên bản mới và tóm tắt các thay đổi. Sử dụng các nhãn và tiêu đề PR để hướng dẫn các mục trong changelog.
# Update version in relevant files
# Update CHANGELOG.md
Push Nhánh Phát Hành: Push nhánh phát hành mới tạo lên repository từ xa.
git push origin releases/vX.X.X
- Tạo Tag Phát Hành: Khi nhánh phát hành đã được push và tất cả các kiểm tra CI đều thành công, tạo một tag cho phiên bản phát hành.
git tag vX.X.X
- Push Tag: Push tag lên repository từ xa. Hành động này có thể kích hoạt các pipeline CI/CD được thiết kế để deploy/phát hành phiên bản mới.
git push origin vX.X.X
- Kích Hoạt CI: Nếu pipeline CI/CD của bạn không tự động kích hoạt khi push tag, hãy kích hoạt thủ công pipeline để build, test, và deploy/phát hành phiên bản mới như đã cấu hình.
Kết Luận
Vậy là chúng ta đã hoàn thành hướng dẫn publish một thư viện Kotlin Multiplatform lên GitHub Packages. Đây là ví dụ kết quả khi bạn publish thành công. Tham khảo thêm tại github Hy vọng rằng bài viết này đã giúp bạn hiểu rõ hơn về quy trình và cảm thấy tự tin hơn khi thực hiện. Chúc bạn thành công và đừng quên chia sẻ thành quả của mình với mọi người nhé! Nếu bạn có bất kỳ câu hỏi nào, đừng ngần ngại để lại bình luận. Tôi luôn sẵn sàng giúp đỡ!
Happy coding! 🚀