A sbt plugin for publishing your project to the Maven central repository through the REST API of Sonatype Nexus. Deploying artifacts to Sonatype repository is a requirement for synchronizing your projects to the Maven central repository. sbt-sonatype plugin enables two-step release of your Scala/Java projects.
publishSigned
(with sbt-pgp plugin)
publishTo := sonatypePublishToBundle.value
to your build.sbtsonatypeBundleRelease
(New in sbt-sonatype 3.4)
sonatypeSessionName
key, sbt-sonatype will discard them properly.After these steps, your project will be synchronized to the Maven central within ten minutes. No longer need to enter the web interface of Sonatype Nexus repository to perform these release steps.
Create a Sonatype Repository account
Related articles:
Import sbt-sonatype plugin and sbt-pgp plugin to use sonatypeBundleRelease
and publishSigned
commands:
// For sbt 1.x (sbt-sonatype 2.3 or higher)
addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "(version)")
addSbtPlugin("com.github.sbt" % "sbt-pgp" % "2.1.2")
// For sbt 0.13.x (upto sbt-sonatype 2.3)
addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "(version)")
addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.0.0")
⚠️ Legacy Host
By default, this plugin is configured to use the legacy Sonatype repository
oss.sonatype.org
. If you created a new account on or after February 2021, addsonatypeCredentialHost
settings:// For all Sonatype accounts created on or after February 2021 import xerial.sbt.Sonatype.sonatype01 ThisBuild / sonatypeCredentialHost := sonatype01
As of early 2024, Sonatype has switched all new account registration over to the Sonatype Central portal and legacy sonatype.org
accounts will eventually migrate there. To configure sbt to publish to the Sonatype Central portal, simply add the following:
import xerial.sbt.Sonatype.sonatypeCentralHost
ThisBuild / sonatypeCredentialHost := sonatypeCentralHost
To use sbt-sonatype, you need to create a bundle of your project artifacts (e.g., .jar, .javadoc, .asc files, etc.) into a local folder specified by sonatypeBundleDirectory
. By default, the folder is (project root)/target/sonatype-staging/(version)
. Add the following publishTo
setting to create a local bundle of your project:
publishTo := sonatypePublishToBundle.value
With this setting, publishSigned
will create a bundle of your project to the local staging folder. If the project has multiple modules, all of the artifacts will be assembled into the same folder to create a single bundle.
If isSnapshot.value
is true (e.g., if the version name contains -SNAPSHOT), publishSigned task will upload files to the Sonatype Snapshots repository without using the local bundle folder.
If necessary, you can tweak several configurations:
val sonatypeCentralDeploymentName =
settingKey[String]("Deployment name. Default is <organization>.<artifact_name>-<version>")
// [Optional] If you need to manage the default Sonatype Central deployment name, change the setting below.
// If publishing multiple modules, ensure that this is set on the module level, rather than on the build level.
sonatypeCentralDeploymentName := s"${organization.value}.${name.value}-${version.value}"
// [Optional] The local staging folder name:
sonatypeBundleDirectory := (ThisBuild / baseDirectory).value / target.value.getName / "sonatype-staging" / (ThisBuild / version).value
// [Optional] If you need to manage unique session names by yourself, change this default setting:
sonatypeSessionName := s"[sbt-sonatype] ${name.value} ${version.value}"
// [Optional] Timeout until giving up sonatype close/promote stages. Default is 60 min.
sonatypeTimeoutMillis := 60 * 60 * 1000
// [If you cannot use bundle upload] Use this setting when you need to uploads artifacts directly to Sonatype
// With this setting, you cannot use sonatypeBundleXXX commands
publishTo := sonatypePublishTo.value
// [If necessary] Settings for using custom Nexus repositories:
sonatypeCredentialHost := "s01.oss.sonatype.org"
sonatypeRepository := "https://s01.oss.sonatype.org/service/local"
For the authentication to Sonatype API, you need to set your Sonatype token information (name and password) in the global sbt settings. To protect your password, never include this file within your project. Get the token from https://oss.sonatype.org or https://s01.oss.sonatype.org.
credentials += Credentials("Sonatype Nexus Repository Manager",
"oss.sonatype.org",
"(Sonatype token user name)",
"(Sonatype token password)")
sbt-sonatype is an auto-plugin, which will automatically configure your build. There are a few settings though that you need to define by yourself:
sonatypeProfileName
org.xerial
. If you do not set this value, it will be the same with the organization
value.pomExtra
Example settings:
// Your profile name of the sonatype account. The default is the same with the organization value
sonatypeProfileName := "(your organization. e.g., org.xerial)"
// To sync with Maven central, you need to supply the following information:
publishMavenStyle := true
// Open-source license of your choice
licenses := Seq("APL2" -> url("http://www.apache.org/licenses/LICENSE-2.0.txt"))
// Where is the source code hosted: GitHub or GitLab?
import xerial.sbt.Sonatype._
sonatypeProjectHosting := Some(GitHubHosting("username", "projectName", "user@example.com"))
// or
sonatypeProjectHosting := Some(GitLabHosting("username", "projectName", "user@example.com"))
// or if you want to set these fields manually
homepage := Some(url("https://(your project url)"))
scmInfo := Some(
ScmInfo(
url("https://github.com/(account)/(project)"),
"scm:git@github.com:(account)/(project).git"
)
)
developers := List(
Developer(id="(your id)", name="(your name)", email="(your e-mail)", url=url("(your home page)"))
)
The basic steps for publishing your artifact to the Central Repository are as follows:
publishSigned
to deploy your artifact to a local staging repository.sonatypeBundleRelease
(since sbt-sonatype 3.4)
; sonatypePrepare; sonatypeBundleUpload; sonatypeRelease
.sonatypeRelease
will do sonatypeClose
and sonatypePromote
in one step.
sonatypeClose
closes your staging repository at Sonatype. This step verifies Maven central sync requirement, GPG-signature, javadoc
and source code presence, pom.xml settings, etc.sonatypePromote
command verifies the closed repository so that it can be synchronized with Maven central.Note: If your project version has "SNAPSHOT" suffix, your project will be published to the snapshot repository of Sonatype, and you cannot use sonatypeBundleUpload
or sonatypeRelease
command.
Usually, we only need to run sonatypeBundleRelease
command in sbt-sonatype:
sonatypeCredentialHost
is set to a host other than the Sonatype Central portal, this command will run a sequence of commands ; sonatypePrepare; sonatypeBundleUpload; sonatypeRelease
in one step.sonatypeCredentialHost
is set to the Sonatype Central portal, this command will default to the sonatypeCentralRelease command.publishSigned
before this command to create a local staging bundle.publishSigned
before this command to create a local staging bundle.publish
in the Sonatype Central portal in order to release it. This command will fail if the bundle does not pass initial validation after being uploaded.publishSigned
before this command to create a local staging bundle.sonatypeSessionName
as a unique key.sonatypePublishTo
setting.sonatypeOpen
before each upload to reuse the already created stging repository.publishSigned
task. For small/medium-size projects, using only sonatypePrepare
would work.sonatypeSessionName
as a unique key. If it doesn't exist, create a new one. It will updatesonatypePublishTo
sonatypeSessionName
key.> ; publishSigned; sonatypeBundleRelease
For cross-building projects, use + publishSigned
:
> ; + publishSigned; sonatypeBundleRelease
When you are sharing a working folder, you can parallelize publishSigned step for each module or for each Scala binary version:
sonatypeBundleRelease
If you are not sharing any working directory (e.g., Travis CI), to parallelize the release process, you need to publish a bundle for each build because Sonatype API only supports uploading one bundle per a staging repository.
Here is an example to parallelize your build for each Scala binary version:
sonatypeSessionName := "[sbt-sonatype] ${name.value}-${scalaBinaryVersion.value}-${version.value}"
to use unique session keys for individual Scala binary versions.sbt ++(Scala version) "; publishSigned; sonatypeBundleRelease"
For sbt-sonatype 2.x:
To perform publishSigned and sonatypeBundleRelease with sbt-release plugin, define your custom release process as follows:
import ReleaseTransformations._
releaseCrossBuild := true // true if you cross-build the project for multiple Scala versions
releaseProcess := Seq[ReleaseStep](
checkSnapshotDependencies,
inquireVersions,
runClean,
runTest,
setReleaseVersion,
commitReleaseVersion,
tagRelease,
// For non cross-build projects, use releaseStepCommand("publishSigned")
releaseStepCommandAndRemaining("+publishSigned"),
releaseStepCommand("sonatypeBundleRelease"),
setNextVersion,
commitNextVersion,
pushChanges
)
If your Maven project (including Gradle, etc.) is already deployed to the staging repository of Sonatype, you can use sbt sonatypeReleaseAll (sonatypeProfileName)
command
for the synchronization to the Maven central (Since version 0.5.1).
Prepare the following two files:
addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "(version)")
credentials += Credentials("Sonatype Nexus Repository Manager",
"oss.sonatype.org",
"(Sonatype user name)",
"(Sonatype password)")
Alternatively, the credentials can also be set with the environment variables SONATYPE_USERNAME
and SONATYPE_PASSWORD
.
Then, run sonatypeReleaseAll
command by specifying your sonatypeProfileName
. If this is org.xerial
, run:
$ sbt "sonatypeReleaseAll org.xerial"
Releasing sbt-sonatype to Sonatype:
## Add a new git tag
$ git tag v3.9.x
$ ./sbt
> publishSigned
> sonatypeBundleRelease