Публикация библиотеки в Maven Central — руководство

Выберите и подтвердите пространство имен

Вам потребуется подтвержденное пространство имен, чтобы однозначно идентифицировать артефакты вашей библиотеки в Maven Central.

Артефакты Maven идентифицируются по координатам, например, com.example:fibonacci-library:1.0.0. Эти координаты состоят из трех частей, разделенных двоеточиями:

• groupId в обратной DNS-форме, например, com.example

• artifactId: уникальное имя самой библиотеки, например, fibonacci-library

• version: строка версии, например, 1.0.0. Версия может быть любой строкой, но не может заканчиваться на -SNAPSHOT

Зарегистрированное пространство имен позволяет задать формат groupId в Maven Central. Например, если вы зарегистрируете пространство имен com.example, можно будет публиковать артефакты со значением com.example, com.example.libraryname, com.example.module.feature и так далее для groupId.

Войдя в Maven Central, перейдите на страницу Namespaces. Затем нажмите кнопку Add Namespace и зарегистрируйте пространство имен:

brew install gpg

./gradlew uploadPublicPgpKey --keyring /path_to/build/pgp/public_KEY_ID.asc

gpg --keyserver keyserver.ubuntu.com --send-keys F175482952A225BFC4A07A715EE6B5F76620B385CE

gpg --armor --export-secret-keys F175482952A225BFC4A07A715EE6B5F76620B385CE > key.gpg

Подготовьте проект библиотеки

Если вы начали разработку библиотеки на основе шаблонного проекта, сейчас самое время заменить заданные по умолчанию названия на название вашей библиотеки. Это касается названия модуля библиотеки и названия корневого проекта в файле build.gradle.kts верхнего уровня.

Если в проекте есть целевая платформа Android, выполните шаги по подготовке выпуска библиотеки Android. Как минимум, необходимо указать подходящее пространство имен для библиотеки, чтобы при компиляции ресурсов был создан уникальный класс R. Обратите внимание: это пространство имен отличается от пространства имен Maven, созданного ранее.

// build.gradle.kts

android {
    namespace = "io.github.kotlinhandson.fibonacci"
}

Настройте плагин публикации

В этом руководстве для публикации в Maven Central используется vanniktech/gradle-maven-publish-plugin. Подробнее о преимуществах плагина можно прочитать здесь. Обратитесь к документации плагина, чтобы узнать больше о его использовании и доступных параметрах настройки.

Чтобы добавить плагин в проект, добавьте следующую строку в блок plugins {} файла build.gradle.kts модуля библиотеки:

// <module directory>/build.gradle.kts

plugins {
    id("com.vanniktech.maven.publish") version "0.37.0" 
}

В том же файле добавьте следующую конфигурацию, заменив все значения на подходящие для вашей библиотеки:

// <module directory>/build.gradle.kts

mavenPublishing {
    publishToMavenCentral()
    
    signAllPublications()
    
    coordinates(group.toString(), "fibonacci", version.toString())
    
    pom { 
        name = "Fibonacci library"
        description = "A mathematics calculation library."
        inceptionYear = "2024"
        url = "https://github.com/kotlin-hands-on/fibonacci/"
        licenses {
            license {
                name = "The Apache License, Version 2.0"
                url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
                distribution = "https://www.apache.org/licenses/LICENSE-2.0.txt"
            }
        }
        developers {
            developer {
                id = "kotlin-hands-on"
                name = "Kotlin Developer Advocate"
                url = "https://github.com/kotlin-hands-on/"
            }
        }
        scm {
            url = "https://github.com/kotlin-hands-on/fibonacci/"
            connection = "scm:git:git://github.com/kotlin-hands-on/fibonacci.git"
            developerConnection = "scm:git:ssh://git@github.com/kotlin-hands-on/fibonacci.git"
        }
    }
}

Наиболее важные параметры:

• coordinates, задающие groupId, artifactId и version вашей библиотеки.

• Лицензия, на условиях которой публикуется библиотека.

• Сведения о разработчиках, содержащие список авторов библиотеки.

• Сведения о SCM (управлении исходным кодом), указывающие, где размещен исходный код библиотеки.

Выполните локальные проверки

Перед публикацией в Maven Central рекомендуется локально проверить правильность конфигурации проекта.

./gradlew checkSigningConfiguration

./gradlew checkPomFileFor<PUBLICATION_NAME>Publication

./gradlew checkPomFileForMavenPublication

Создайте токен пользователя

Для авторизации запросов на публикацию в Maven Central вам понадобится токен доступа Maven. Откройте страницу Setup Token-Based Authentication и нажмите кнопку Generate User Token.

В результате вы получите данные, как в примере ниже: имя пользователя и пароль. Если вы потеряете эти учетные данные, их придется создать заново, так как Maven Central их не хранит.

<server>
    <id>${server}</id>
    <username>l2nfaPmz</username>
    <password>gh9jT9XfnGtUngWTZwTu/8141keYdmQpipqLPRKeDLTh</password>
</server>

Добавьте секреты в GitHub

Чтобы использовать ключи и учетные данные, необходимые для публикации в рабочем процессе GitHub Action, и при этом сохранить их конфиденциальность, сохраните эти значения в качестве секретов.

1. На странице Settings репозитория GitHub нажмите Security | Secrets and variables | Actions.

2. Нажмите кнопку New repository secret и добавьте следующие секреты:

   • MAVEN_CENTRAL_USERNAME и MAVEN_CENTRAL_PASSWORD — это значения токена пользователя, созданные на сайте Central Portal.

   • SIGNING_KEY_ID — это последние 8 символов идентификатора ключа подписи, например, 20B385CE для F175482952A225BFC4A07A715EE6B5F76620B385CE.

   • SIGNING_PASSWORD — это парольная фраза, заданная при создании ключа GPG.

   • GPG_KEY_CONTENTS должен содержать все содержимое файла key.gpg.

   

На следующем шаге вы укажете имена этих секретов в конфигурации CI.

Добавьте рабочий процесс GitHub Actions в проект

Вы можете настроить непрерывную интеграцию для автоматической сборки и публикации библиотеки. В качестве примера мы воспользуемся GitHub Actions.

Для начала добавьте в репозиторий следующий рабочий процесс в файле .github/workflows/publish.yml:

# .github/workflows/publish.yml

name: Publish
on:
  release:
    types: [released, prereleased]
jobs:
  publish:
    name: Release build and publish
    runs-on: macOS-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4
      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: 21
      - name: Publish to MavenCentral
        run: ./gradlew publishToMavenCentral --no-configuration-cache
        env:
          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
          ORG_GRADLE_PROJECT_signingInMemoryKeyId: ${{ secrets.SIGNING_KEY_ID }}
          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }}
          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.GPG_KEY_CONTENTS }}

После фиксации и отправки этого файла рабочий процесс будет запускаться автоматически при создании релиза (включая предварительный релиз) в репозитории GitHub, где размещен проект. Рабочий процесс получает текущую версию кода, настраивает JDK, а затем запускает задачу Gradle publishToMavenCentral.

При использовании задачи publishToMavenCentral вам все равно нужно будет проверить и вручную выпустить развертывание на сайте Maven Central. Кроме того, можно использовать задачу publishAndReleaseToMavenCentral для полной автоматизации процесса выпуска.

Вы также можете настроить рабочий процесс на запуск при отправке тега в репозиторий.

Для этого действия необходимы данные для подписи и учетные данные Maven Central, которые вы создали в качестве секретов репозитория.

Конфигурация рабочего процесса автоматически передает эти секреты в переменные среды, делая их доступными процессу сборки Gradle.

Создайте релиз на GitHub

Настроив рабочий процесс и секреты, вы готовы создать релиз, который запустит публикацию библиотеки.

1. Убедитесь, что в файле build.gradle.kts вашей библиотеки указана версия, которую вы хотите опубликовать.

2. Перейдите на главную страницу репозитория GitHub.

3. На боковой панели справа нажмите Releases.

4. Нажмите кнопку Draft a new release (или Create a new release, если вы еще не создавали релизы для этого репозитория).

5. Каждому релизу соответствует тег. Создайте новый тег в раскрывающемся списке тегов и задайте название релиза (имя тега и название могут совпадать).

   Скорее всего, они должны совпадать с номером версии библиотеки, указанным в файле build.gradle.kts.

   

6. Еще раз проверьте ветку, для которой создается релиз (особенно если это не ветка по умолчанию), и добавьте подходящие примечания к выпуску новой версии.

7. Установите флажки под описанием, чтобы отметить релиз как предварительный (это удобно для предварительных версий, таких как alpha, beta или RC).

   Также можно отметить релиз как последний, если для этого репозитория уже создавались релизы.

8. Нажмите кнопку Publish release, чтобы создать новый релиз.

9. В верхней части страницы репозитория GitHub нажмите вкладку Actions. Здесь вы увидите, что новый релиз запустил рабочий процесс публикации.

   Нажмите на рабочий процесс, чтобы просмотреть результаты задачи публикации.

10. После завершения рабочего процесса перейдите на панель управления Deployments в Maven Central. Здесь должно появиться новое развертывание.

    Пока Maven Central выполняет проверки, развертывание может некоторое время оставаться в состояниях pending или validating.

11. Когда развертывание перейдет в состояние validated, проверьте, что оно содержит все загруженные артефакты. Если все в порядке, нажмите кнопку Publish, чтобы выпустить эти артефакты.

    

Чтобы автоматически выпускать артефакты после проверки развертывания, замените задачу publishToMavenCentral в рабочем процессе на publishAndReleaseToMavenCentral.