22
Publish your Scala project to Maven in 5 minutes with Sonatype
Say what you will about JavaScript, but npm has made it incredibly easy for anyone to publish code. In just a few clicks, you can share a library to make others' lives easier, or publish a little snippet like left-pad to cause endless headaches.
Java has long had the Maven repository (and accompanying build tool of the same name), which serves a similar purpose: sharing packaged code.
But it can be intimidating for a newbie to publish to Maven -- that's where Sonatype comes in.
Sonatype, Inc.'s Central Repository (a complement to Apache's Maven repository) makes it super easy to share code. With just a few lines and a few manual steps, you can publish your package to Maven, and others can easily import it and use it.
sbt's Using Sonatype guide and Sonatype's Deployment Guide cover probably 95% of what you need to know for this process, but there are a few gotchas that I'll highlight below using the ❗ exclamation point emoji.
Note: throughout this guide, I assume that your source code is hosted in a GitHub repository, and so all instructions are GitHub-specific.
Sonatype syncs with Maven, and so to publish to Maven, you can publish via Sonatype. To do so, you'll need a Sonatype Jira account to create an issue. Do that by clicking here to create an account and then clicking here to create a Jira issue.
As an example, here is the ticket I opened to publish a project of mine to Maven. If you want to publish multiple packages to Maven using Sonatype, you'll need to create multiple Jira tickets, but you only need the one user account.
The fields in the Jira are easy to fill out:
This should include the name of the project. In my case, I'm publishing a small project hosted at https://github.com/awwsmm/zepto, so I've included the name "zepto" in the Jira summary.
This should be something like io.github.awwsmm, or similar for your GitHub username. See this guide for more information on package coordinates.
❗ GOTCHA: this should not be something like
com.github.awwsmm.com.githubcoordinates are no longer supported.
This is where users can go on the web to find information about your project. For me, that's https://github.com/awwsmm/zepto, but it could be a github.io page or a page on your personal website, or whatever.
This is the URL that your source code is hosted at. For me, that's https://github.com/awwsmm/zepto.git.
We'll use a PGP key to sign this package, so users can be confident that you are the person who created it. To do this, you can mostly follow the instructions from scala-sbt.org...
Install GnuPG (on macOS, you can do this via brew install gnupg) and verify that it's installed by checking the version
$ gpg --version
gpg (GnuPG) 2.3.1
...Next, generate a key...
$ gpg --gen-key...list your keys...
$ gpg --list-keys
gpg: checking the trustdb
gpg: marginals needed: 3 completes needed: 1 trust model: pgp
gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2023-07-11
/Users/andrew.watson/.gnupg/pubring.kbx
---------------------------------------
pub ed25519 2021-07-11 [SC] [expires: 2023-07-11]
1234517530FB96F147C6A146A326F592D39AAAAA
uid [ultimate] Andrew Watson <[email protected]>
sub cv25519 2021-07-11 [E] [expires: 2023-07-11]...and distribute the key to some GPG keyserver, like
$ gpg --keyserver keyserver.ubuntu.com --send-keys
1234517530FB96F147C6A146A326F592D39AAAAA
gpg: sending key A326F592D39AAAAA to hkp://keyserver.ubuntu.com❗ GOTCHA: scala-sbt's guide tells you to distribute the key to
hkp://pool.sks-keyservers.net, but this causes akeyserver send failed: No nameerror, as the keyserver is no longer active. You can instead use any other major GPG keyserver, like the Ubuntu one I used above.
addSbtPlugin("com.github.sbt" % "sbt-pgp" % "2.1.2")The latest version of this plugin can be found at the GitHub page for the project.
Next, add your credentials to your project by following the instructions in Step 3 here. I'll reproduce them to be clear...
Create a file at
$HOME/.sbt/1.0/sonatype.sbtAnd add the following line to it
credentials += Credentials(Path.userHome / ".sbt" / "sonatype_credentials")Then, create the credentials file at
~/.sbt/sonatype_credentialsAdd the following information to that file
realm=Sonatype Nexus Repository Manager
host=s01.oss.sonatype.org
user=<your username>
password=<your password>The user and password here are the same username and password you used when creating your account on Sonatype's Jira server in Step 1. You don't need to worry about putting anything in quotes here -- spaces are fine. But...
❗ GOTCHA: ...be careful! The guide at
scala-sbt.orgsays to sethost=oss.sonatype.org, but this has recently changed tohost=s01.oss.sonatype.org. More information about this change can be found here.
The penultimate step in this process is to configure your project for publishing, by adding a bunch of information to either your project's build.sbt (or, as I recommend) publish.sbt file.
Replace username with your GitHub username below, project with the name of the project (in my case, these are awwsmm and zepto, respectively), and all the other obvious fill-in bits, and paste it into a publish.sbt file at the root of your project
ThisBuild / organization := "io.github.username"
ThisBuild / organizationName := "username"
ThisBuild / organizationHomepage := Some(url("https://www.yourwebsite.com"))
ThisBuild / scmInfo := Some(
ScmInfo(
url("https://github.com/username/project"),
"scm:[email protected]/project.git"
)
)
ThisBuild / developers := List(
Developer(
id = "username",
name = "Your Name Goes Here",
email = "[email protected]",
url = url("https://www.yourwebsite.com")
)
)
ThisBuild / description := "Describe your project here..."
ThisBuild / licenses := List("The Unlicense" -> new URL("https://unlicense.org/"))
ThisBuild / homepage := Some(url("https://github.com/username/project"))
// Remove all additional repository other than Maven Central from POM
ThisBuild / pomIncludeRepository := { _ => false }
ThisBuild / publishTo := {
val nexus = "https://s01.oss.sonatype.org/"
if (isSnapshot.value) Some("snapshots" at nexus + "content/repositories/snapshots")
else Some("releases" at nexus + "service/local/staging/deploy/maven2")
}
ThisBuild / publishMavenStyle := true
ThisBuild / versionScheme := Some("early-semver")You can set the licenses to whatever you feel is appropriate. Here is GitHub's guide to choosing a license for your repo -- though be aware that they probably ignore it anyway.
❗ GOTCHA: Notice that we've also used
s01.oss.sonatype.orgabove!
Once you've got all of that set up, you should be able to publish your project from the sbt shell with the publishSigned command
sbt:zepto> publishSigned
[info] Wrote /local/path/to/zepto_2.13-0.4.0.pom
[info] published zepto_2.13 to https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/io/github/awwsmm/zepto_2.13/0.4.0/zepto_2.13-0.4.0-sources.jar
[info] published zepto_2.13 to https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/io/github/awwsmm/zepto_2.13/0.4.0/zepto_2.13-0.4.0-javadoc.jar
[info] published zepto_2.13 to https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/io/github/awwsmm/zepto_2.13/0.4.0/zepto_2.13-0.4.0-javadoc.jar.asc
...You can use your Sonatype username and password to log in to https://s01.oss.sonatype.org/ where you should now see your (pre-release) project!
Select the project, click Close from the menu, and then Release. You should see your project on Maven almost immediately, though it will take a few hours to show up in the search engine.
...and that's it!
You should now be able to import your published library into other projects by adding
"io.github.awwsmm" %% "zepto" % "0.4.0"(or whatever is appropriate) to the libraryDependencies in the build.sbt of another project.
I wrote this guide mostly as a way to remember the GOTCHAs I encountered above, but hopefully it makes it easier for someone else to publish their Scala project to Maven. It's something I've wanted to try for a while but didn't get around to until recently.
Feel free to comment below with any questions or suggestions you may have. And thanks for reading!
22