Selles artiklis käsitlen ma üksikasjalikult Java artefakti avaldamise protsessi nullist läbi Github Actions Sonatype Maven Central Repository's, kasutades Gradle'i ehitajat.

Otsustasin selle artikli kirjutada seoses korraliku õpetuse puudumisega ühest kohast. Kõik vajalik teave tuli kokku koguda erinevatest, mitte just uusimatest allikatest. Kes on huvitatud, on teretulnud edasi lugema.

Repo loomine Sonatype'is

Esimese etapina peame looma repot Sonatype Maven Centralis. Selleks liigume siia, registreerime end ja loome uue ülesande, paludes meil repo luua. Sisestame oma GroupId VK grupp projekti URL-i lingi projekti jaoks ja SCM url versioonihaldussüsteemi lingi, kus projekt asub. GroupId see peaks olema vormis com.example, com.example.domain, com.example.testsupport, samuti võib olla lingina teie githubi kontole: github.com/yourusername -> io.github.yourusername. Igatahes peate tõendama selle domeeni või profiili omaniku. Kui olete märkinud githubi profiili, palutakse luua avalik repo soovitud nimega.

Mõne aja pärast pärast kinnitamist loodetakse teie GroupId'i ja saame edasi liikuda järgmise sammu, Gradle'i konfigureerimise juurde.

Konfigureerime Gradle'i

Artikli kirjutamise hetkeks ei leidnud ma Gradle'i jaoks lisandeid, mis aitaksid artefakti avaldamisel. See Ainus leitud plugin, kuid autor on sellest loobunud. Seetõttu otsustasin kõik ise teha, õnneks pole see liiga keeruline.

Esimene samm on välja selgitada Sonatype'i avaldamise nõuded. Need on järgmised:

Allikakoode ja JavaDoc'i olemasolu, st peavad olema olemas -sources.jar ja-javadoc.jar failid. Nagu dokumentatsioonis öeldud, kui allikakoode või dokumentatsiooni ei ole võimalik esitada, võib teha tühja faili -sources.jar või -javadoc.jar lihtsa README'ga, et läbida kontroll.
Kõik failid peavad olema allkirjastatud GPG/PGP, ja .asc fail, mis sisaldab allkirja, peab olema kaasatud iga faili jaoks.
Olemasolu pom faile
Sobivad väärtused groupId, artifactId ja version. Versioon võib olla suvaline string ja ei tohi lõppeda -SNAPSHOT
Peab olema olemas name, description ja url
Teave litsentsi, arendajate ja versioonihalduse kohta peab olema olemas.

Need on põhireeglid, mida tuleb avaldamisel järgida. Täielik teave on saadaval siit.

Rakendame need nõuded build.gradle faili. Esmalt lisame kogu vajaliku teabe arendajate, litsentsi, versioonikontrolli süsteemi kohta, samuti määrame projekti URL-i, nime ja kirjelduse. Selleks kirjutame lihtsa meetodi:

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

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

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

            description 'Mõned artefakti kirjeldused'
            name 'Artefakti nimi'
            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 'The Apache License, Version 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'
                }
            }
        }
    }
}

Seejärel tuleb märkida, et ehituse käigus genereeritakse -sources.jar ja-javadoc.jar failid. Selleks tuleb sektsiooni java lisada järgmine:

java {
    withJavadocJar()
    withSourcesJar()
}

Liigume viimase nõudmise juurde, GPG/PGP allkirja seadistamine. Selleks ühendame pistikprogrammi allkirjastamine:

plugins {
    id 'signing'
}

Ja lisame sektsiooni :

signing {
    sign publishing.publications
}

Lõpuks lisame sektsiooni 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
            }
        }
    }
}

Siit sonatypeUsername ja sonatypePassword muutujad, mis sisaldavad sisselogimis- ja parooliteavet, mis loodi registreerimisel sonatype.org.

Seega näeb lõplik build.gradle välja järgmine:

Täielik kood 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 'Mõned artefakti kirjeldavad andmed'
            name 'Artefakti nimi'
            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 'Apache License, Versioon 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'
                }
            }
        }
    }
}

Tahan märkida, et versiooni saame keskkonnamuutujast: System.getenv('RELEASE_VERSION'). Seadistame selle üles ehituse käigus ja võtame sildi nimest.

PGP võtme genereerimine

Üks Sonatype'i nõudeid on iga faili allkirjastamine GPG/PGP võtmega. Selleks läheme siia ja laadime alla GnuPG utiliidi oma operatsioonisüsteemi jaoks.

Genereerime võtme paari: gpg --gen-key, sisestame kasutajanime, e-posti aadressi ja määrame parooli.
Selgitame välja id oma võtme käsuga: gpg --list-secret-keys --keyid-format short. Id on märgitud kaldkriipsu taha, näiteks: rsa2048/9B695056
Avaldame avaliku võtme serverisse https://keys.openpgp.org käsklusega: gpg --keyserver [https://keys.openpgp.org](https://keys.openpgp.org/) --send-keys 9B695056
Eksportime salajase võtme suvalisse kohta, see on meil hiljem vajalik: gpg --export-secret-key 9B695056 > D:\gpg\9B695056.gpg

Seame üles Github Actions

Liigume lõpetava sammu juurde, seadistame ehituse ja automaatse avaldamise, kasutades Github Actions.
Github Actions on funktsionaalsus, mis võimaldab automatiseerida töövoogu, rakendades täislahendust CI/CD. Ehitamine, testimine ja juurutamine võivad käivituda erinevate sündmuste korral: koodi pushimine, väljaande loomine või probleemide esitamine. See funktsionaalsus on täiesti tasuta avalike hoidlate jaoks.

Selles osas näitan, kuidas seadistada koodi kogumist ja edastamist ning juurutamist Sonatype'i hoidlasse väljaande vabastamisel, samuti kuidas seadistada salaandmeid.

Seadistame saladused

Automaatseks kogumiseks ja juurutamiseks vajame mitmeid salajasi väärtusi, nagu võtme ID, parool, mille sisestasime võtme genereerimise ajal, PGP võtme enda ning Sonatype'i sisselogimise/parooli. Neid saab seadistada hoidlakontrollide seadete spetsiaalses vaates:

Seadistame järgmised muutujad:

SONATYPE_USERNAME/SONATYPE_PASSWORD — sisselogimine/parool, mida kasutasime Sonatype'i registreerimisel
SIGNING_KEYID/SIGNING_PASSWORD — PGP võtme ID ja parool, mille seadsime üles genereerimise ajal.

Muutuja GPG_KEY_CONTENTS kohta tahan peatuda lähemalt. Asi on selles, et väljaandmiseks on meil vajalik privaatne PGP võti. Selle salajastesse asetamiseks kasutasin juhendit ja tegin täiendavalt hulga toiminguid.

Šifreerime meie võti kasutades gpg: gpg --symmetric --cipher-algo AES256 9B695056.gpg, sisestades parooli. See tuleks asetada muutujasse: SECRET_PASSPHRASE
Tõlkime saadud šifreeritud võtme tekstivormingusse kasutades base64: base64 9B695056.gpg.gpg > 9B695056.txt. Sisu asetame muutujasse: GPG_KEY_CONTENTS.

Koodi jõudmisel ja PR-i loomisel seadistamine

Esmalt tuleb luua kaust oma projekti juures: .github/workflows.

Sinna tuleb paigutada fail, näiteks gradle-ci-build.yml järgnevate sisu kujul:

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}}

See töövoog käivitub, kui pusitakse harudesse master, dev ja testing, samuti pull requestide loomisel.

Jaotises jobs on märgitud sammud, mis tuleb jooksutada vastavalt nimetatud sündmustele. Antud juhul ehitame me viimasel versioonil ubuntu, kasutame Java 8-ndat ning samuti kasutame Gradle’i pistikut eskatos/gradle-command-action@v1, mis kasutab viimasel versioonil kokkuvõtjate käivitamiseks antud käske argumentide. Muutujad secrets.SONATYPE_USERNAME ja secrets.SONATYPE_PASSWORD need on varad, mille me eelnevalt määrasime.

Kogumise tulemused kajastuvad vahekaardil Actions:

Autodeploy uue väljaande väljalaskmisel

Autodeploy jaoks loome töövoo jaoks eraldi faili gradle-ci-publish.yml:

nimi: publish

sisse:
  push:
    sildid:
      - 'v*'

tööd:
  publish:
    töötab: ubuntu-latest
    sammud:
      - kasutab: actions/checkout@v1
      - nimi: Seadista JDK 8
        kasutab: actions/setup-java@v1
        with:
          java-versioon: 8

      - nimi: Valmistuge avaldamiseks
        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}"

      - nimi: Avaldage Gradlega
        kasutab: eskatos/gradle-command-action@v1
        with:
          gradle-versioon: current
          argumentide: test publish -Psigning.secretKeyRingFile=secret.gpg -Psigning.keyId=${{secrets.SIGNING_KEYID}} -Psigning.password=${{secrets.SIGNING_PASSWORD}} -PsonatypeUsername=${{secrets.SONATYPE_USERNAME}} -PsonatypePassword=${{secrets.SONATYPE_PASSWORD}}

Fail on peaaegu identne eelmisega, välja arvatud sündmus, millega see aktiveeritakse. Antud juhul on see sildiga loomise sündmus, mis algab tähekombinatsiooniga v.

Enne juurutamist peame tõmbama PGP võtme saladustest ning asetama selle projekti juurkausta ja dekrüpteerima selle. Edasi peame seadistama spetsiaalse keskkonnamuutuja RELEASE_VERSION millele viitame gradle.build failis. Kõik see toimub osas Valmistuge avaldamiseks. Saame meie võti muutuja GPG_KEY_CONTENTS, muundame selle gpg-failiks ja dekrüpteerime selle, asetades faili secret.gpg.

Järgmisena tutvume erimuutuja GITHUB_REF, millest saame välja võtta versiooni, mille määrasime sildi loomisel. Sel juhul on selle muutuja väärtus refs/tags/v0.0.2 , millest lõikame maha esimesed 11 sümbolit, et saada täpselt versioon. Edasi kasutame standardseid Gradle käske avaldamiseks: test publish

Kinnitus tulemuste deploimisel Sonatype’i registrisse

Pärast versiooni loomist peab käivituma eelnevas jaotises kirjeldatud töövoog. Selleks loome väljalaske:

samal ajal peab sildi nimi algama v-tähega. Kui pärast Publish release'i nupule vajutamist töövoog edukalt töötab, saame minna Sonatype Nexus et seda kinnitada:

Artefakt ilmub Staging registrisse. Alguses on see olekus Open, seejärel tuleb see käsitsi sulgeda, vajutades vastavat nuppu. Pärast kõigi nõuete täitmise kontrollimist läheb artefakt olekusse Close ja ei ole enam muudetav. Sellisel kujul jõuab see MavenCentralisse. Kui kõik on hästi, saab vajutada nuppu Release, sel juhul jõuab artefakt Sonatype’i registrisse.

Kuna artefakt jõuda MavenCentral-i, tuleb seda taotleda ülesandes, mille me alguses lõime. Seda on vaja teha ainult üks kord, kuna me avaldame seda esmakordselt. Edaspidi ei ole seda enam vajalik, kõik sünkroniseeritakse automaatselt. Sünkroniseerimise lubamine toimus kiiresti, kuid et artefakt oleks MavenCentralis kergesti kätte saadav, läks umbes 5 päeva.

Sellega on kõik, oleme avaldanud oma artefakti MavenCentralis.