Hướng Dẫn Sử Dụng Maven Publish và GitHub Actions Để Publish Thư Viện Kotlin Multiplatform Lên GitHub Packages

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 url sẽ có dạng: https://maven.pkg.github.com/<github-user>/<repo-name>
• 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.
  • artifactId cho các target sẽ có dạng <artifact>cho common, và <artifact>-android, <artifact>-iosx64, <artifact>-js, <artifact>-jvm cho 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ằng v.

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! 🚀