How to use this plugin in a local project

July 20, 2022 ยท View on GitHub

I have used this plugin before

  1. Apply Gradle plugin 
    plugins {
   id("me.him188.maven-central-publish") version "1.0.0-dev-1"
}
  2. Configure mavenCentralPublish
    Raed MavenCentralPublishExtension.pomConfigurators for required information, or simply configure a GitHub project like: 
    mavenCentralPublish {
    singleDevGithubProject("Him188", "yamlkt")
    licenseFromGitHubProject("Apache-2.0", "master")
}
  3. Set credentials: set any of Gradle property, JVM property, JVM or system environment variable named publication.credentials or PUBLICATION_CREDENTIALS
  4. Finish. Run task publish.

I am new to publication

If you publish your artifact (namely your project files) to Maven Central repository, anyone can access your files directly, in Gradle by declaring mavenCentral() repository and in maven that is already done by default.

Anyone can publish artifacts to the Maven Central repository (MC in short), however MC has strict rules.

If you are a personal developer, you usually don't need to pay specific attention to these rule, just follow this guide and use this plugin.

Register and activate Sonatype account

Follow steps 1 to 7 described by How to Publish Your Artifacts to Maven Central . (Thanks to the original author)

Get Sonatype User Token

https://oss.sonatype.org/ or new server https://s01.oss.sonatype.org

As of February 2021, all new projects began being provisioned on https://s01.oss.sonatype.org/

  1. Login with your Sonatype account
  2. On the upper right corner, click your username
  3. Click Profile
  4. Click Summary and choose User Token
  5. Access User Token
  6. Note down the username and password, this will be your Sonatype User Token.

You can also use this pair of username and password to log into your account, so it is just like another way to access your Sonatype account, but you can reset the User Token so it is more safe.

Generate key pair

  1. Generate a key pair

    1. Install GnuPG (Binary releases)

    2. Download key-gen.sh ( from Karlatemp/PublicationSign by @Karlatemp)

    3. Execute key-gen.sh, and you will get keys.gpg.pub and keys.gpg that are to be used later.

      • keys.gpg.pub: the public key
      • keys.gpg: the private key

Make sure that your GPG Key has no password otherwise you cannot sign your artifacts successfully.

  1. Upload the key pair to a public keyserver

    https://keys.openpgp.org/

    Open keys.gpg.pub as a text file, upload its content to the website.

Prepare credentials

Credentials is a pack of your Sonatype user and key pair that can be re-used for further publications.

  1. Download a generator from releases
  2. Create a directory, place the following files into it.
    • the generator you just downloaded
    • keys.gpg.pub: your GnuPG public key
    • keys.gpg: your GnuPG private key
    • sonatype.txt: a text file that contains your Sonatype User Token, with username in the first line, and the password in the second line.
  3. Execute the generator.
  4. The keys are packed into a file credentials.txt, the content of which is your credentials

You can re-use the credentials for all of your projects.

Then follow the chapter I already had credentials.

I already had credentials

You need credentials, otherwise read I am new to publication first.

1. Apply Gradle plugin

Note that the plugin should be applied before any other plugins, in other words, at the first line of plugins block.

The plugin should be applied to the subproject that needs to be published. Applying the plugin to the root project will not affect subprojects.

Using build.gradle.kts

plugins {
    id("me.him188.maven-central-publish") version "1.0.0-dev-1"
    // then apply other plugins if needed
}

Using build.gradle

plugins {
    id 'net.mamoe.maven-central-publish' version '1.0.0-dev-1 
    // then apply other plugins if needed
}

2. Configure publishing

Determining which server to deploy to

If your Sonatype account was created after February 2021, you may need to use the new server.

mavenCentralPublish {
    useCentralS01() // use new server
    // ... add other configurations
}

When you get error about 'Unauthorized' when executing the task publish, you might consider using the new or the old server (by removing the useCentralS01()).

You can read more on the official documentation

Single developer GitHub project

A simple configurator for GitHub projects with single developer.

mavenCentralPublish {
    singleDevGithubProject("GitHub username of the owner of the repository", "GitHub repository name")
    licenseFromGitHubProject("Open-source License name", "Repository main branch name")
}

A real example from yamlkt:

mavenCentralPublish {
    singleDevGithubProject("Him188", "yamlkt")
    licenseFromGitHubProject("Apache-2.0", "master")
}

Multi developers GitHub project

mavenCentralPublish {
    githubProject("GitHub username of the owner of the repository", "GitHub repository name")
    licenseFromGitHubProject("Open-source License name", "Repository main branch name")
    developer("Developer1")
    developer("Developer2") // add as many as needed
}

Other projects: Set manually

Read MavenCentralPublishExtension.publicationConfigurators for detailed manual configurations.

3. Add credentials

You should have got credentials previously, then follow one of the following methods.

Set in gradle.properties

In your GRADLE_HOME (to set globally) or project dir (to set locally), open or create gradle.properties, append a line:

publication.credentials=CONTENT OF credentials.txt

This should be like:

publication.credentials=0afc0c2d2d2d2... (very long)

Set in system environment

Add a system environment variable named publication.credentials or PUBLICATION_CREDENTIALS with the content of *** credentials.txt*** (not the file path)

Set in JVM environment

Add an JVM environment variable named publication.credentials or PUBLICATION_CREDENTIALS with the content of *** credentials.txt*** (not the file path)

Set in Gradle command line

Add argument -Ppublication.credentials=CONTENT OF credentials.txt.

Load manually on configuration

mavenCentralPublish {
    credentials = TODO() // provide a PublicationCredentials instance.
}

4. Finish

Now you can execute the publish task to upload artifacts. If you want to use this plugin a second time, just read I have used this plugin before

After uploading the artifacts

When publish executed successfully, you need to do close and release on Sonatype https://oss.sonatype.org/#stagingRepositories.

If a close has failed, it means this plugin has done something wrong. Please report to issues.

If all succeed, your repository will be in Maven Central and can be accessed publicly. You can check on https://mvnrepository.com/.

Automation

close and release can be done automatically by another plugin https://github.com/bmuschko/gradle-nexus-plugin.
maven-central-publish has already configured that for you. You can execute task closeAndReleaseRepository in root project.

However, this can only handle single publication. If you publish multiple modules at one time, you can only close and release on the Sonatype website.