В тази статия искам подробно да разгледам процеса на публикуване от нулата на Java артефакт чрез Github Actions в Sonatype Maven Central Repository, използвайки Gradle.

Реших да напиша тази статия, тъй като липсваше нормален туториал на едно място. Цялата информация беше събирана на части от различни източници, като не бяха съвсем актуални. На когото му е интересно, добре дошли под кат.

Създаване на репозитория в Sonatype

Първата стъпка е да създадем репозиторий в Sonatype Maven Central. За целта отиваме тук, регистрираме се и създаваме нова задача с молба да ни създадат репозиторий. Въвеждаме нашия GroupId проект, URL на проекта линк към проекта и SCM url линк към системата за контрол на версиите, в която се намира проектът. GroupId тук трябва да е от вида com.example, com.example.domain, com.example.testsupport, а също така може да бъде и под формата на линк към вашия GitHub: github.com/yourusername -> io.github.yourusername. Във всеки случай, ще трябва да потвърдите собствеността на домейна или профила. Ако сте посочили профил в GitHub, ще ви помолят да създадете публичен репозиторий с нужното име.

След известно време след потвърждаването, вашият GroupId ще бъде създаден и можем да преминем към следващата стъпка, конфигурирането на Gradle.

Конфигурираме Gradle

Към момента на писане на статията не намерих плъгини за Gradle, които да помогнат с публикуването на артефакт. Това единственият плъгин, който намерих, обаче авторът се отказа от неговата по-нататъшна поддръжка. Затова реших да направя всичко сам, благо не е прекалено трудно.

Първото, което трябва да изясним, е изискванията на Sonatype за публикуване. Те са следните:

• Наличие на изходен код и JavaDoc, т.е. трябва да присъстват -sources.jar и-javadoc.jar файлове. Както е посочено в документацията, ако не е възможно да се предоставят изходни кодове или документация, може да се направи пустословие -sources.jar или -javadoc.jar c с прост README вътре, за да премине проверката.
• Всички файлове трябва да бъдат подписани с помощта на GPG/PGP, и .asc файл, съдържащ подписа, трябва да бъде включен за всеки файл.
• Наличието pom файла
• Коректни стойности groupId, artifactId и version. Версията може да бъде произволен низ и не може да завършва -SNAPSHOT
• Необходимо е присъствието на име, описание и url
• Информация за лиценза, разработчиците и системата за контрол на версиите

Това са основните правила, които трябва да бъдат спазвани при публикуването. Пълна информация е налична тук.

Реализираме тези изисквания в build.gradle файле. Първо, нека добавим цялата необходима информация за разработчиците, лиценза, системата за контрол на версиите, както и да зададем url, име и описание на проекта. За целта ще напишем прост метод:

def customizePom(pom) {
    pom.withXml {
        def root = asNode()

        root.dependencies.removeAll { dep ->
            dep.scope == "test"
        }

        root.children().last() + {
            resolveStrategy = DELEGATE_FIRST

            description 'Некое описание на артефакта'
            name 'Име на артефакт'
            url 'https://github.com/login/projectname'
            organization {
                name 'com.github.login'
                url 'https://github.com/login'
            }
            issueManagement {
                system 'GitHub'
                url 'https://github.com/login/projectname/issues'
            }
            licenses {
                license {
                    name 'Лиценз на Apache, версия 2.0'
                    url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
                }
            }
            scm {
                url 'https://github.com/login/projectname'
                connection 'scm:https://github.com/login/projectname.git'
                developerConnection 'scm:git://github.com/login/projectname.git'
            }
            developers {
                developer {
                    id 'dev'
                    name 'DevName'
                    email 'email@dev.ru'
                }
            }
        }
    }
}

Следва да упоменем, че при изграждането трябва да се генерират -sources.jar и-javadoc.jar файлове. За целта в секцията java трябва да добавим следното:

java {
    withJavadocJar()
    withSourcesJar()
}

Преминаваме към последното изискване, настройката на GPG/PGP подписа. За целта ще добавим плъгин signing:

plugins {
    id 'signing'
}

И ще добавим секция:

signing {
    sign publishing.publications
}

Накрая, добавяме секция publishing:

publishing {
    publications {
        mavenJava(MavenPublication) {
            customizePom(pom)
            groupId group
            artifactId archivesBaseName
            version version

            from components.java
        }
    }
    repositories {
        maven {
            url "https://oss.sonatype.org/service/local/staging/deploy/maven2"
            credentials {
                username sonatypeUsername
                password sonatypePassword
            }
        }
    }
}

Тук sonatypeUsername и sonatypePassword переменные, съдържащи логин и парола, създадени при регистрацията на sonatype.org.

Така финалният build.gradle ще изглежда по следния начин:

Пълен код build.gradle

plugins {
    id 'java'
    id 'maven-publish'
    id 'signing'
}

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
    withJavadocJar()
    withSourcesJar()
}

group 'io.github.githublogin'
archivesBaseName = 'projectname'
version = System.getenv('RELEASE_VERSION') ?: "0.0.1"

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.5.2'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.5.2'
}

test {
    useJUnitPlatform()
}

jar {
    from sourceSets.main.output
    from sourceSets.main.allJava
}

signing {
    sign publishing.publications
}

publishing {
    publications {
        mavenJava(MavenPublication) {
            customizePom(pom)
            groupId group
            artifactId archivesBaseName
            version version

            from components.java
        }
    }
    repositories {
        maven {
            url "https://oss.sonatype.org/service/local/staging/deploy/maven2"
            credentials {
                username sonatypeUsername
                password sonatypePassword
            }
        }
    }
}

def customizePom(pom) {
    pom.withXml {
        def root = asNode()

        root.dependencies.removeAll { dep ->
            dep.scope == "test"
        }

        root.children().last() + {
            resolveStrategy = DELEGATE_FIRST

            description 'Some description of artifact'
            name 'Artifact name'
            url 'https://github.com/login/projectname'
            organization {
                name 'com.github.login'
                url 'https://github.com/githublogin'
            }
            issueManagement {
                system 'GitHub'
                url 'https://github.com/githublogin/projectname/issues'
            }
            licenses {
                license {
                    name 'The Apache License, Version 2.0'
                    url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
                }
            }
            scm {
                url 'https://github.com/githublogin/projectname'
                connection 'scm:https://github.com/githublogin/projectname.git'
                developerConnection 'scm:git://github.com/githublogin/projectname.git'
            }
            developers {
                developer {
                    id 'dev'
                    name 'DevName'
                    email 'email@dev.ru'
                }
            }
        }
    }
}

Искам да отбележа, че версията получаваме от променливата на средата: System.getenv('RELEASE_VERSION'). Ще я зададем при изграждането и ще я вземем от името на тага.

Генериране на PGP ключ

Едно от изискванията на Sonatype е подписването на всички файлове с помощта на GPG/PGP ключ. За целта отиваме тук и сваляме утилитата GnuPG за операционната си система.

• Генерираме ключова двойка: gpg --gen-key, въвеждаме име на потребител, имейл, както и задаваме парола.
• Установяваме ид нашия ключ с командата: gpg --list-secret-keys --keyid-format short. Id-то ще бъде посочено след наклонената черта, например: rsa2048/9B695056
• Публикуваме публичния ключ на сървъра https://keys.openpgp.org с командата: gpg --keyserver [https://keys.openpgp.org](https://keys.openpgp.org/) --send-keys 9B695056
• Експортираме секретния ключ на произволно място, той ни е нужен по-късно: gpg --export-secret-key 9B695056 > D:\gpg\9B695056.gpg

Настройваме Github Actions

Преминаваме към последния етап, настройваме изграждането и авто публикуването с помощта на Github Actions.
Github Actions – функционал, позволяващ автоматизация на работния процес, реализиращ пълен цикъл CI/CD. Сборката, тестването и деплойването могат да бъдат инициирани от различни събития: прикачване на код, създаване на релиз или issues. Тази функционалност е напълно безплатна за публични репозитории.

В този раздел ще покажа как да конфигурирате сборката и разпращането на код, както и деплойването в репозиторий на Sonatype при издаване на релиз, както и настройката на тайни.

Задаваме тайни

За автоматична сборка и деплой ни е необходима поредица от тайни стойности, като id на ключа, паролата, която въведохме при генерирането на ключа, самият PGP ключ, както и логин/парола за Sonatype. Можем да ги зададем в специален раздел в настройките на репозитория:

Задаваме следните променливи:

• SONATYPE_USERNAME/SONATYPE_PASSWORD – логин/парола, които въведохме при регистрацията в Sonatype
• SIGNING_KEYID/SIGNING_PASSWORD – id на PGP ключа и паролата, зададена при генерирането.

Искам да обърна внимание на променливата GPG_KEY_CONTENTS. Факт е, че за публикуването ни е необходим затворен PGP ключ. За да го поставя в тайните, използвах инструкцията и допълнително извърших ред действия.

• Шифроваме нашия ключ с помощта на gpg: gpg --symmetric --cipher-algo AES256 9B695056.gpg, въвеждайки паролата. Тя трябва да бъде поставена в променливата: SECRET_PASSPHRASE
• Превеждаме получения шифрован ключ в текстов формат с помощта на base64: base64 9B695056.gpg.gpg > 9B695056.txt. Съдържанието поставяме в променливата: GPG_KEY_CONTENTS.

Настройка на сборката при прикачване на код и създаване на PR

За начало е необходимо да създадете папка в корена на вашия проект: .github/workflows.

В нея разпределете файл, например, gradle-ci-build.yml со следующим содержимым:

name: build

on:
  push:
    branches:
      - master
      - dev
      - testing
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Set up JDK 8
        uses: actions/setup-java@v1
        with:
          java-version: 8

      - name: Build with Gradle
        uses: eskatos/gradle-command-action@v1
        with:
          gradle-version: current
          arguments: build -PsonatypeUsername=${{secrets.SONATYPE_USERNAME}} -PsonatypePassword=${{secrets.SONATYPE_PASSWORD}}

Този работен процес ще бъде изпълнен при прикачване в клоновете master, dev и тест, също и при създаване на pull request.

В секцията jobs са указани стъпките, които трябва да се изпълнят при посочените събития. В този случай ще извършваме сборка на последната версия на ubuntu, ще използваме Java 8, както и плъгин за Gradle eskatos/gradle-command-action@v1, който, използвайки последната версия на сборщика, ще стартира командите, посочени в arguments. Променливи secrets.SONATYPE_USERNAME и secrets.SONATYPE_PASSWORD това са тайните, които зададохме по-рано.

Резултатите от изграждането ще се отразят в раздела Actions:

Автоматично внедряване при нова версия

За автоматично внедряване ще създадем отделен файл на работния процес gradle-ci-publish.yml:

name: publish

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Настройка на JDK 8
        uses: actions/setup-java@v1
        with:
          java-version: 8

      - name: Подготовка за публикуване
        run: |
          echo '${{secrets.GPG_KEY_CONTENTS}}' | base64 -d > publish_key.gpg
          gpg --quiet --batch --yes --decrypt --passphrase="${{secrets.SECRET_PASSPHRASE}}" 
          --output secret.gpg publish_key.gpg
          echo "::set-env name=RELEASE_VERSION::${GITHUB_REF:11}"

      - name: Публикуване с Gradle
        uses: eskatos/gradle-command-action@v1
        with:
          gradle-version: current
          arguments: test publish -Psigning.secretKeyRingFile=secret.gpg -Psigning.keyId=${{secrets.SIGNING_KEYID}} -Psigning.password=${{secrets.SIGNING_PASSWORD}} -PsonatypeUsername=${{secrets.SONATYPE_USERNAME}} -PsonatypePassword=${{secrets.SONATYPE_PASSWORD}}

Файлът е практически идентичен на предишния, освен събитието, при което ще се задейства. В този случай става въпрос за събитие на създаване на таг с име, започващо с v.

Преди внедряване трябва да извлечем PGP ключа от тайните и да го поставим в корена на проекта, както и да го декриптираме. След това трябва да зададем специална променлива на средата RELEASE_VERSION към която се обръщаме в gradle.build файла. Всичко това става в секцията Prepare to publish. Получаваме нашия ключ от променливата GPG_KEY_CONTENTS, превръщаме го в gpg файл, след което го декриптираме и помещаваме в файл secret.gpg.

След това се обръщаме към специална променлива GITHUB_REF, от която можем да вземем версията, зададена при създаването на тага. Тази променлива в случая има стойност refs/tags/v0.0.2 , от която изрязваме първите 11 символа, за да получим конкретната версия. След това стандартно използваме команди от Gradle за публикуване: test publish

Проверка на резултатите от внедряването в репозиторий на Sonatype

След създаването на версията трябва да стартира работният процес, описан в предишния раздел. За целта създаваме версия:

като името на тага трябва да започва с v. Ако след натискане на Publish release работният процес успее, можем да влезем в Sonatype Nexus за да се уверим в това:

Артефакт се появи в Staging репозитория. Първоначално той е в статус Open, след което трябва ръчно да бъде прехвърлен в статус Close, като се натисне съответният бутон. След проверка на изпълнението на всички изисквания, артефактът преминава в статус Close и вече не е достъпен за промяна. В такъв вид той ще попадне в MavenCentral. Ако всичко е наред, може да натиснете бутона Release, като по този начин артефактът ще влезе в репозитория Sonatype.

За да попадне артефактът в MavenCentral, трябва да поискаме това в задачата, която създадохме в самото начало. Това трябва да се направи само един път, тъй като публикуваме за първи път. При последващи публикации това не е необходимо, всичко ще се синхронизира автоматично. Синхронизацията беше активирана бързо, но за да стане артефактът достъпен в MavenCentral, преминаха около 5 дни.

С това приключваме, публикувахме нашия артефакт в MavenCentral.

Полезни линкове

• Подобна статия, само че публикацията е през maven
• Staging репозиторий Sonatype
• Jira Sonatype, в който трябва да се създаде задача
• Пример репозитория, където всичко е настроено

Източник: habr.com