I denne artikkelen ønsker jeg å gå gjennom prosessen med å publisere en Java-artifakt fra bunnen av via Github Actions til Sonatype Maven Central Repository ved å bruke Gradle-byggeren.

Jeg valgte å skrive denne artikkelen på grunn av mangel på et godt tutorial på ett sted. All informasjon måtte samles bit for bit fra ulike kilder, som ikke alltid var helt oppdaterte. Den som er interessert, er velkommen til å lese videre.

Oppretting av depot i Sonatype

Første steg er å opprette et depot i Sonatype Maven Central. For å gjøre dette går vi til her, registrerer oss og oppretter en ny forespørsel om å opprette depotet vårt. Vi fyller inn vår GroupId prosjektet, Prosjektets URL lenke til prosjektet og SCM-url lenke til versjonskontrollsystemet der prosjektet ligger. GroupId her må være i formatet com.example, com.example.domain, com.example.testsupport, og kan også være en lenke til din GitHub: github.com/yourusername -> io.github.yourusername. Uansett må du bekrefte eierskapet til dette domenet eller profilen. Hvis du angav GitHub-profil, blir det bedt om å opprette et offentlig depot med det ønskede navnet.

Etter en tid, etter bekreftelse, vil GroupId bli opprettet, og vi kan gå videre til neste steg, konfigurasjon av Gradle.

Konfigurerer Gradle

På tidspunktet for skrivingen av artikkelen fant jeg ikke noen plugins for Gradle som kunne hjelpe med publikasjonen av artifakten. Dette den eneste pluginen jeg fant, men forfatteren har trukket seg fra videre støtte. Så jeg valgte å gjøre alt selv, heldigvis er det ikke for vanskelig.

Det første som må avklares, er Sonatype's krav til publisering. De er som følger:

Tilstedeværelse av kildekoder og JavaDoc, dvs. må være til stede -sources.jar og-javadoc.jar filer. Som beskrevet i dokumentasjonen, hvis du ikke kan gi kildekodene eller dokumentasjonen, kan du lage en dummy -sources.jar eller -javadoc.jar med et enkelt README inni, for å bestå kontrollen.
Alle filer må være signert med GPG/PGP, og .asc filen som inneholder signaturen, må inkluderes for hver fil.
Tilstedeværelsen av pom filen
Korrekte verdier for groupId, artifactId og version. Versjonen kan være en vilkårlig streng og kan ikke slutte med -SNAPSHOT
Det må være tilstedeværelse av name, beskrivelse og url
Tilstedeværelse av informasjon om lisenser, utviklere og versjonskontrollsystem

Dette er de grunnleggende reglene som må følges ved publisering. Fullstendig informasjon er tilgjengelig her.

Vi implementerer disse kravene i build.gradle I filen. Først vil vi legge til all nødvendig informasjon om utviklerne, lisensen, versjonskontrollsystemet, samt spesifisere URL, navn og beskrivelse av prosjektet. For dette vil vi skrive en enkel metode:

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

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

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

            description 'Noen beskrivelse av artefakt'
            name 'Artefaktnavn'
            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.no'
                }
            }
        }
    }
}

Deretter må vi spesifisere at filene blir generert under byggingen. -sources.jar og-javadoc.jar For dette, i seksjonen java må vi legge til følgende:

java {
    withJavadocJar()
    withSourcesJar()
}

La oss gå videre til det siste kravet, oppsett av GPG/PGP-signatur. For dette vil vi aktivere pluginnen signing:

plugins {
    id 'signing'
}

Og vi legger til seksjonen:

signing {
    sign publishing.publications
}

Til slutt, la oss legge til seksjonen 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
            }
        }
    }
}

Her sonatypeUsername og sonatypePassword variablene som inneholder brukernavn og passord, laget ved registrering på sonatype.org.

Dermed er den endelige build.gradle vil se slik ut:

Full koden til 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'
                }
            }
        }
    }
}

Jeg vil merke at vi får versjonen fra miljøvariabelen: System.getenv('RELEASE_VERSION'). Vi vil angi den under byggingen og ta den fra tag-navnet.

Generering av PGP-nøkkel

En av kravene fra Sonatype er at alle filer må signeres med en GPG/PGP-nøkkel. For dette går vi her og laster ned GnuPG-verktøyet for vårt operativsystem.

Vi genererer et nøkkelpar: gpg --gen-key, skriver inn brukernavn, e-post, og setter et passord.
Vi finner ut id om nøkkelen vår ved å bruke kommandoen: gpg --list-secret-keys --keyid-format short. Id vil bli angitt etter skråstreken, for eksempel: rsa2048/9B695056
Vi publiserer den offentlige nøkkelen til serveren https://keys.openpgp.org kommandoen: gpg --keyserver [https://keys.openpgp.org](https://keys.openpgp.org/) --send-keys 9B695056
Vi eksporterer den hemmelige nøkkelen til et vilkårlig sted, da vi vil trenge den senere: gpg --export-secret-key 9B695056 > D:\gpg\9B695056.gpg

Vi konfigurerer Github Actions

La oss gå til den avsluttende fasen, hvor vi konfigurerer bygging og automatisk publisering ved hjelp av Github Actions.
Github Actions – en funksjonalitet som gjør det mulig å automatisere arbeidsflyten ved å implementere en full CI/CD-syklus. Bygging, testing og distribusjon kan utløses av forskjellige hendelser, som koding, opprettelse av utgivelser eller issues. Denne funksjonaliteten er helt gratis for offentlige repositories.

I denne delen vil jeg vise hvordan du setter opp bygging og koding, samt distribusjon til Sonatype-repoet ved utgivelsen av en release, samt innstillingen av hemmeligheter.

Sett opp hemmeligheter

For automatisk bygging og distribusjon trenger vi en rekke hemmelige verdier, som nøkkel-id, passordet vi satte under genereringen av nøkkel, selve PGP-nøkkelen, samt bruker-/passord for Sonatype. Disse kan settes i en spesialseksjon i repoets innstillinger:

Angi følgende variabler:

SONATYPE_USERNAME/SONATYPE_PASSWORD – brukernavn/passord vi oppga ved registrering i Sonatype
SIGNING_KEYID/SIGNING_PASSWORD – id for PGP-nøkkelen og passordet satt ved genereringen.

Jeg vil gjerne stoppe opp ved variabelen GPG_KEY_CONTENTS. Det er slik at vi trenger den private PGP-nøkkelen for publisering. For å lagre den i hemmeligheter, benyttet jeg instruksjonen og i tillegg gjorde jeg en rekke handlinger.

La oss kryptere nøkkelen med gpg: gpg --symmetric --cipher-algo AES256 9B695056.gpg, ved å skrive inn passordet. Dette bør plasseres i variabelen: SECRET_PASSPHRASE
La oss konvertere den krypterte nøkkelen til tekstformat ved hjelp av base64: base64 9B695056.gpg.gpg > 9B695056.txt. Innholdet skal plasseres i variabelen: GPG_KEY_CONTENTS.

Innstilling av bygging ved koding og opprettelse av PR

Først må du lage en mappe i roten av prosjektet ditt: .github/workflows.

I den legger du inn en fil, for eksempel, gradle-ci-build.yml med innholdet:

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

Denne arbeidsflyten vil bli utført når det pushes til grenene master, dev og testing, samt når pull-forespørselen opprettes.

I seksjonen jobs er stegene angitt som skal utføres ved de angitte hendelsene. I dette tilfellet vil vi bygge på den nyeste versjonen av ubuntu, bruke Java 8, samt bruke plugin for Gradle eskatos/gradle-command-action@v1, som ved å bruke den nyeste versjonen av byggeverktøyet vil kjøre kommandoene som angitt i argumentsVariabler secrets.SONATYPE_USERNAME og secrets.SONATYPE_PASSWORD dette er hemmeligheter vi satte tidligere.

Byggeresultatene vil bli vist i fanen Actions:

Automatisk distribusjon ved utgivelse av ny versjon

For automatisk distribusjon oppretter vi en egen arbeidsflyttingsfil 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}}

Filen er praktisk talt identisk med den forrige, unntatt for hendelsen som utløser den. I dette tilfellet er det hendelsen som oppretter et tag med navn som starter med v.

Før distribusjon må vi hente PGP-nøkkelen fra hemmelighetene og plassere den i prosjektets rot, samt dekryptere den. Videre må vi sette en spesialmiljøvariabel RELEASE_VERSION som vi refererer til i gradle.build filen. Alt dette gjøres i delen Prepare to publish. Vi får nøkkelen vår fra variabelen GPG_KEY_CONTENTS, konverterer den til en gpg-fil, deretter dekrypterer vi den og plasserer den i filen secret.gpg.

Deretter refererer vi til en spesialvariabel GITHUB_REF, fra hvilken vi kan hente versjonen vi spesifiserte ved opprettingen av taggen. Denne variabelen har i dette tilfellet verdien refs/tags/v0.0.2 fra hvilken vi kutter de første 11 tegnene for å spesifisere versjonen. Videre bruker vi standard Gradle-kommandoer for publisering: test publish

Sjekk resultatene av distribusjonen i Sonatype-repositoriet

Etter opprettelse av versjonen bør arbeidsflyten beskrevet i forrige del starte. For dette oppretter vi en utgivelse:

hvor taggnavnet må starte med v. Når arbeidsflyten har kjørt vellykket etter å ha klikket på Publiser utgivelse, kan vi gå til Sonatype Nexus for å bekrefte dette:

Artefakten har dukket opp i Staging-repositoriet. Den vises først i status Open, deretter må den manuelt endres til status Close ved å trykke på den aktuelle knappen. Etter at alle krav er oppfylt, går artefakten til status Close og er ikke lenger tilgjengelig for endringer. I denne formen vil den bli sendt til MavenCentral. Hvis alt er i orden, kan du trykke på knappen Release, og artefakten vil havne i Sonatype-repositoriet.

For at artefakten skal komme til MavenCentral, må vi be om dette i oppgaven vi opprettet i starten. Dette må gjøres bare én gang, da vi publiserer for første gang. Ved påfølgende publiseringer er dette ikke nødvendig, alt vil synkroniseres automatisk. De fikk meg raskt i gang med synkroniseringen, men det tok omtrent 5 dager før artefakten ble tilgjengelig i MavenCentral.

Det er alt, vi har publisert artefakten vår i MavenCentral.