Selles artiklis tahan ma üksikasjalikult sõnastada Java artefakti nullist avaldamise protsessi GitHub Actions kaudu Sonatype Maven Central Repository's, kasutades Gradle'i kogujat.

Selle artikli kirjutamine oli vajalik, kuna puudusid korralikud õpetused ühes kohas. Kõik teave pidi olema kogutud erinevatest allikatest, mis ei olnud ka kuigi värsked. Kui see teema sind huvitab, oled teretulnud lugema edasi.

Sonatype'i repositooriumi loomine

Esimese sammuna peame looma repositooriumi Sonatype Maven Centralis. Selleks suundume siia, registreerime end ja loome uue ülesande, paludes luua meile repositoorium. Sisestame oma GroupId for the project, Projekti URL projekti lingi ja SCM url versioonihaldussüsteemi lingi, kus projekt asub. GroupId see peaks olema kujul com.example, com.example.domain, com.example.testsupport, kuid võib olla ka lingina sinu GitHubi kontole: github.com/yourusername -> io.github.yourusername. Igal juhul pead sa kinnitama selle domeeni või profiili omamist. Kui sa märkisid GitHubi profiili, palutakse sul luua avalik repositoorium soovitud nimega.

Mõne aja pärast, kui kinnitamine on tehtud, luuakse sinu GroupId ja saame liikuda järgmise sammu juurde, Gradle'i konfigureerimise juurde.

Konfigureerime Gradle'i

Artikli kirjutamise hetkel ei leidnud ma Gradle'i pluginaid, mis võiksid aita artefakti avaldamisel. See on ainult ühe plugina, mille leidsin, kuid autor loobus selle edasise toe andmisest. Seetõttu otsustasin teha kõik ise, õnneks pole see liiga keeruline.

Esimene asi, mis tuleb välja selgitada, on Sonatype'i nõuded avaldamiseks. Need on järgmised:

Allika- ja JavaDoc-failide olemasolu, st need peavad olema olemas -sources.jar ja-javadoc.jar failid. Nagu dokumentatsioonis öeldakse, kui allikaid või dokumentatsiooni pole võimalik esitada, võib teha tühja failiga, milles on lihtne README, et läbida kontroll. -sources.jar või -javadoc.jar Kõik failid peavad olema allkirjastatud kasutades
GPG/PGP .asc, ja fail, mis sisaldab allkirja, peab olema kaasatud iga faili jaoks. pom
Standardsete moodulite komplekti olemasolu Korrektsed väärtused failist
groupId artifactId, . Versioon võib olla suvaline string ja ei tohi lõppeda ja version-SNAPSHOT Peab olema olemas
Teave litsentsi, arendajate ja versioonihaldussüsteemi kohta nimi, kirjeldus ja url
Need on peamised reeglid, mida tuleb järgida avaldamisel. Täielik teave on saadaval

Rakendame need nõuded siin.

järgmiseks build.gradle failis. Esiteks lisame kogu vajaliku teabe arendajate, litsentsi, versioonihalduse 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 kirjeldused artefaktist'
            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 '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 'ArendajaNimi'
                    email 'email@dev.ru'
                }
            }
        }
    }
}

Seejärel tuleb määrata, et ehitamisel genereeritaks -sources.jar ja-javadoc.jar failid. Selleks sektsiooni java tuleb lisada järgmine:

java {
    withJavadocJar()
    withSourcesJar()
}

Liigume viimase nõude juurde, GPG/PGP allkirja seadistamine. Selleks ühendame plugina signing:

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

Siin sonatypeUsername ja sonatypePassword muutujad, mis sisaldavad sisselogimis- ja parooliteavet, loodud registreerumisel sonatype.org.

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

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 'Some description of artifact'
            name 'Artifct 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'
                }
            }
        }
    }
}

Tahan märkida, et versiooni saame keskkonna muutujast: System.getenv('RELEASE_VERSION'). Seadistame selle koostamise ajal ja võtame sildist.

PGP võtme genereerimine

Üks Sonatype'i nõudeid on, et kõik failid tuleb allkirjastada GPG/PGP võtmega. Selleks läheme siia ja laadime alla GnuPG utiliidi oma operatsioonisüsteemi jaoks.

Genereerime võtmepaari: gpg --gen-key, sisestame kasutajanime, e-posti aadressi ning määrame parooli.
Selgitame välja id oma võtme, kasutades käsku: gpg --list-secret-keys --keyid-format short. Id on märgitud pärast kaldkriipsu, näiteks: rsa2048/9B695056
Avaldame avaliku võti serverisse https://keys.openpgp.org with the command: gpg --keyserver [https://keys.openpgp.org](https://keys.openpgp.org/) --send-keys 9B695056
Eksportime salajase võtme suvalisse kohta, seda vajame hiljem: gpg --export-secret-key 9B695056 > D:\gpg\9B695056.gpg

Seadistame Github Actions

Liigume lõpetamise etappi, seadistame koostamise ja automaatse avaldamise, kasutades Github Actions.
Github Actions – funktsioon, mis võimaldab automatiseerida töövoogu, realiseerides täieliku CI/CD tsükli. Kogumine, testimine ja deploy võivad olla käivitatud erinevate sündmuste tõttu: koodi pushimine, väljalaske loomine või issues. See funktsioon on täiesti tasuta avalike repo jaoks.

Selles osas näitan, kuidas seadistada koodi kogumist ja pushimist ning deploy-d Sonatype repo-s, kui väljastatakse uus versioon, samuti salasõnade seadistamist.

Seadistame saladused

Automaatseks kogumiseks ja deploy-ks vajame rida salajasi väärtusi, nagu võtme ID, parool, mille me sisestasime võtme genereerimisel, ise PGP võti, samuti kasutajanimi/parool Sonatype jaoks. Need saab seadistada repo seadete eraldi osas:

Seadistame järgmised muutujad:

SONATYPE_USERNAME/SONATYPE_PASSWORD — kasutajanimi/parool, mille sisestasime Sonatype registreerimisel
SIGNING_KEYID/SIGNING_PASSWORD — PGP võtme ID ja parool, mis määrati genereerimise ajal.

Muudatavale muutujale GPG_KEY_CONTENTS soovin rohkem tähelepanu pöörata. Fakt on see, et avaldamiseks on meil vaja privaatset PGP võtit. Selle lisamiseks saladustesse kasutasin juhendile ja tegin lisaks rida toiminguid.

Krüpteerime meie võtme gpg abil: gpg --symmetric --cipher-algo AES256 9B695056.gpg, sisestades parooli. Selle tuleks paigutada muutuja sisse: SECRET_PASSPHRASE
Tõlgime saadud krüpteeritud võtme tekstivormingusse base64 abil: base64 9B695056.gpg.gpg > 9B695056.txt. Sisus paigutame muutuja sisse: GPG_KEY_CONTENTS.

Kogumise seadistamine koodi pushimise ja PR loomise ajal

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

Sinna paigutage fail, näiteks gradle-ci-build.yml järjgnevate sisuga:

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ööprotsess käivitub, kui pushitakse harudesse master, dev ja testimine, samuti PR loomise ajal.

Jobs sektsioonis on välja toodud sammud, mis peavad toimuma nimetatud sündmuste kohaselt. Antud juhul kogume viimasel ubuntu versioonil, kasutame Java 8 ja samuti pluginat Gradle jaoks eskatos/gradle-command-action@v1, mis kasutades viimast versiooni kogujast käivitab käsud, mis on määratud — valikulised argumendid. Allpool vaatame lähemalt.. Muutujad secrets.SONATYPE_USERNAME ja secrets.SONATYPE_PASSWORD need on salajane, mille me varem määrasime.

Kogumise tulemused kajastuvad vahekaardil Actions:

Autodeploy uue väljaande avaldamisel

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

name: publish

on:
  push:
    tags:
      - 'v*'

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

      - name: Prepare to publish
        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: Publish with 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}}

Fail on praktiliselt identne eelneva failiga, välja arvatud sündmus, mil see aktiveerub. Antud juhul on see sündmus sildi loomine nimega, mis algab tähega v.

Enne deployimist peame PGP võtme saladustest välja tõmbama ja paigutama selle projekti juurka, samuti dekrüpteerima selle. Edasi peame seadma spetsiaalse keskkonnamuutuja RELEASE_VERSION , millele viitame gradle.build failis. Kõik see on tehtud osas Prepare to publish. Saame meie võtme muutuja GPG_KEY_CONTENTS kaudu, konverteerime selle gpg failiks, seejärel dekrüpteerime, paigutades faili secret.gpg.

Seejärel viitame spetsiaalsele muutujale GITHUB_REF, millest saame välja võtta versiooni, mille oleme määranud sildi loomisel. Antud muutuja väärtus on refs/tags/v0.0.2 , millest kärpime esimesed 11 tähte, et saada just versioon. Edasi kasutame standardseid Gradle käske avaldamiseks: test publish

Kontrollige avaldamise tulemusi Sonatype'i hoidlas

Pärast väljaande loomist peaks algama töövoog, mis on kirjeldatud eelnevas osas. Selleks loome väljaande:

, kusjuures sildi nimi peab algama tähega v. Kui pärast Publish release'i klikkimist töövoog töötab, saame minna Sonatype Nexus , et veenduda selles:

Artefakt ilmus Staging hoidlas. Alguses on see olekus Open, mille järel tuleb see käsitsi sulgeda, vajutades vastavale nupule. Pärast kõigi nõuete täitmise kontrollimist liigub artefakt olekusse Close ja ei ole enam muudetav. Sellisel kujul jõuab see MavenCentralisse. Kui kõik on korras, saab vajutada nuppu Release, sellega satub artefakt Sonatype hoidlasse.

Kuna artefakt jõuaks MavenCentralisse, tuleb seda paluda ülesandes, mille me alguses lõime. Seda tuleb teha ainult üks kord, kuna avaldame esmakordselt. Edaspidi ei ole seda vajalik, kõik sünkroniseeritakse automaatselt. Minu sünkroniseerimine lülitati kiiresti sisse, kuid et artefakt muutuks saadavaks MavenCentralis, kulus umbes 5 päeva.

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