How to Publish a Repo

How to Publish Locally

If you want to publish the changed version of a project locally, on your machine, use this command: sbt publish-local

Publishing to Maven Central

Note: These instructions are for repository administrators only!

Note: All steps following step 4 (including) are obsolete, now that we use the sbt release plugin. Please see this page for the current protocol: How to use the sbt release plugin.

Step 1: Sign Up with Sonatype

• Sonatype is the company that provides support and tools for Maven Central. Crucially, they provide the access point for making projects available in the Maven Central Repository. To publish a project remotely, you need to create a free account on Sonatype's JIRA issue management system: https://issues.sonatype.org/.

• Please request that this account be associated with the clulab.org organization. At this JIRA site, the "Community Support - Open Source Project Reposity Hosting (OSSRH)" project is where we can file an issue to request help, such as connecting a new Sonatype account to the our repositories. https://issues.sonatype.org/browse/OSSRH

• Next, create a file to hold your Sonatype credentials: ~/.sbt/1.0/sonatype.sbt Add your credentials, from the Sonatype account you created in Step 1, to the credentials file:

credentials += Credentials(
  "Sonatype Nexus Repository Manager",
  "oss.sonatype.org",
  "your-login",
  "your-password"
)

An alternative is described here.

• (Once you have a Sonatype account and it is linked to the CLU Lab repositories, Sonatype's online Nexus Repository Manager will be used to manage the publishing lifecycle. https://oss.sonatype.org/)

Step 2: Install the sbt-pgp plugin and set credentials

All artifacts, within a project which is released to Maven, must be signed. This plugin does the artifact signing work for us.

• Install it by creating a plugin file: ~/.sbt/1.0/plugins/gpg.sbt containing this plugin specification:

addSbtPlugin("com.github.sbt" % "sbt-pgp" % "2.1.2")

Additional installation information is available here: http://www.scala-sbt.org/sbt-pgp/

Step 3: Create and Publish PGP keys

All project artifacts must be signed before the project can be released. The Nexus Repository Manager will verify the signing signature against a public key server. If you have not already published a public key, you will need to create and publish one for use with Sonatype.

• You can do this using the either the SBT GPG plugin or the GnuPG program. Both programs seem about the same level of difficulty and are quite compatible: the SBT GPG plugin will look for and use your key rings at the same default location where GnuPG creates them, for example.

• Instructions for using the GPG plugin are here: http://www.scala-sbt.org/sbt-pgp/usage.html and instructions for installing and using the GnuPGP program are here: http://central.sonatype.org/pages/working-with-pgp-signatures.html and repeated here: http://blog.sonatype.com/2010/01/how-to-generate-pgp-signatures-with-maven/

• Note that the crucial steps are: (1) generate a key pair and (2) publish the public key to one or more public key servers. While public keys are synced among key servers, the syncing process may take awhile. Using the plugin or the GnuPG program, you can easily publish your generated public key to several of the major key servers in rapid succession. For example, using GnuPG:

$ gpg --list-keys
/Users/joex/.gnupg/pubring.gpg
--------------------------------
pub   2048R/A6BAB25C 2016-05-25 [expires: 2018-05-25]
uid                  Joe Example (CLU Lab UAZ) <joex@nowhere.com>
$ gpg --keyserver hkp://pool.sks-keyservers.net --send-keys A6BAB25C
$ gpg --keyserver hkp://keyserver.ubuntu.com --send-keys A6BAB25C
$ gpg --keyserver hkp://pgp.mit.edu --send-keys A6BAB25C

Step 4: Publish to the Sonatype server

• Make sure the version numbers match the version you plan to release in build.sbt, CHANGES, README.
• git tag to create a tag with this version number.
• Type sbt publishSigned in the project you plan to release to upload it to a "staging repository" on the Sonatype server. This step is where the SBT PGP plugin automatically creates the signature files necessary for remote publication on Maven Central.

Step 5: Manage the Release of the project using the Nexus Repository Manager

This involves "closing" the project in the Sonatype staging repository, checking for errors, then "releasing" the project.

• Go to https://oss.sonatype.org/index.html#stagingRepositories and login with the account you created in Step 1.
• After login you should see a page with the available staging repositories that looks like this:
• Scroll to the bottom of the page to find your staging repository (the name should start with org.clulab).
• Select the project. Then Close it (using the button in the top bar of the window). Wait a few seconds, then click Refresh.
• Check that the close operation succeeded by clicking on the Activity tab in the bottom half of the screen and selecting your most recent (bottom-most) close operation. Any errors are marked with a red dot and error details are available by clicking on the failed close activity line. Here's an example of a close with errors (not one of ours, of course 😉)
• Since we used the SBT PGP plugin to automatically sign our artifacts (via the 'publishSigned' command), the most common error is likely to be that your public key signature was not yet found on a public key server.
• If the close operation was successful, the Release button should now be active. Click it, and answer Yes to the question about whether the repository should be dropped (this just means it will be removed from Sonatype's list of staging repositories).
• You are done: the repository has now been pushed to Maven, and it should be publicly available in 3-4 hours.
• (See this page for more details: http://central.sonatype.org/pages/releasing-the-deployment.html)

Additional information on the remote publishing process is available here: http://www.scala-sbt.org/release/docs/Using-Sonatype.html.

Advance the version number of the project

Advance the version number of the project, e.g., if you just released 5.8.1 the next version should be 5.8.2-SNAPSHOT. Commit and push the new number.

Rules for CLULab administrators:

• Please do not release a repository without Mihai's approval.
• Please do not create private repositories without Mihai's approval (we have a limited number of these).
• Please do not change any permissions of the teams in the CLULab organization without Mihai's approval.