Skip to content
Newer
Older
100644 192 lines (135 sloc) 9.67 KB
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
1 ---
2 layout: content
3 title: Deploying to Sonatype
4 ---
5
6 Deploying to sonatype is easy! Just follow these simple steps:
7
8 ## First - PGP Signatures ##
9
10 You'll need to PGP sign your artifacts for the Sonatype repository. Don't worry, there's a [plugin for that](http://scala-sbt.org/xsbt-gpg-plugin). Follow the instructions for the plugin and you'll have PGP signed artifacts in no time.
11
12 *Note: The plugin is a jvm-only solution to generate PGP keys and sign artifacts. It can work with the GPG command line tool, but the command line is not needed.*
13
14
15 ## Second - Maven Publishing Settings ##
16
17 To publish to a maven repository, you'll need to configure a few settings so that the correct metadata is generated.
18
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
19
20 publishMavenStyle := true
21
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
22
23 is used to ensure POMs are generated and pushed. Next, you have to set up the repositories you wish to push too. Luckily, Sonatype's OSSRH uses the same URLs for everyone:
24
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
25 publishTo <<= version { (v: String) =>
26 val nexus = "https://oss.sonatype.org/"
27 if (v.trim.endsWith("SNAPSHOT"))
28 Some("snapshots" at nexus + "content/repositories/snapshots")
29 else
30 Some("releases" at nexus + "service/local/staging/deploy/maven2")
31 }
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
32
33 Another good idea is to not publish your test artifacts:
34
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
35 publishArtifact in Test := false
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
36
37 ## Third - POM Metadata ##
38
39 Now, we want to control what's available in the `pom.xml` file. This file describes our project in the maven repository and is used by indexing services for search and discover. This means it's important that `pom.xml` should have all information we wish to advertise as well as required info!
40
41 First, let's make sure no repositories show up in the POM file. To publish on maven-central, all *required* artifacts must also be hosted on maven central. However, sometimes we have optional dependencies for special features. If that's the case, let's remove the repositories for optional dependencies in our artifact:
42
174b969 @Sciss Update src/jekyll/using_sonatype.md
Sciss authored
43 pomIncludeRepository := { _ => false }
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
44
45 Next, the POM metadata that isn't generated by SBT must be added. This is done through the `pomExtra` configuration option:
46
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
47 pomExtra := (
48 <url>http://jsuereth.com/scala-arm</url>
49 <licenses>
50 <license>
51 <name>BSD-style</name>
52 <url>http://www.opensource.org/licenses/bsd-license.php</url>
53 <distribution>repo</distribution>
54 </license>
55 </licenses>
56 <scm>
57 <url>git@github.com:jsuereth/scala-arm.git</url>
58 <connection>scm:git:git@github.com:jsuereth/scala-arm.git</connection>
59 </scm>
60 <developers>
61 <developer>
62 <id>jsuereth</id>
63 <name>Josh Suereth</name>
64 <url>http://jsuereth.com</url>
65 </developer>
66 </developers>)
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
67
3631cc8 @jsuereth Updated sonatype docs.
jsuereth authored
68 Specifically, the `url`, `license`, `scm.url`, `scm.connection` and `developer` sections are required. The above is an example from the [scala-arm](http://jsuereth.com/scala-arm) project.
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
69
174b969 @Sciss Update src/jekyll/using_sonatype.md
Sciss authored
70 *Note* that sbt will automatically inject `licenses` and `url` nodes if they are already present in your build file. Thus an alternative to the above `pomExtra` is to include the following entries:
71
72 licenses := Seq("BSD-style" -> url("http://www.opensource.org/licenses/bsd-license.php"))
73
74 homepage := Some(url("http://jsuereth.com/scala-arm"))
75
76 This might be advantageous if those keys are used also by other plugins (e.g. `ls`). You **cannot use both** the sbt `licenses` key and the `licenses` section in `pomExtra` at the same time, as this will produce duplicate entries in the final POM file, leading to a rejection in Sonatype's staging process.
77
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
78 *The full format of a pom.xml file is [outlined here](http://maven.apache.org/pom.html).*
79
80 ## Fourth - Adding credentials ##
81
2b83db1 @harrah minor fixes
harrah authored
82 The credentials for your Sonatype OSSRH account need to be added somewhere. Common convention is a `~/.sbt/sonatype.sbt` file with the following:
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
83
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
84 credentials += Credentials("Sonatype Nexus Repository Manager",
85 "oss.sonatype.org",
86 "<your username>",
87 "<your password>")
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
88
fc8cd33 @jberkel Fix maruku warning
jberkel authored
89 *Note: The first two strings must be `"Sonatype Nexus Repository Manager"` and `"oss.sonatype.org"` for Ivy to use the credentials.*
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
90
91 ## Finally - Publish ##
92
93 In SBT, run `publish` and you should see something like the following:
94
95 > publish
96 Please enter your PGP passphrase> ***********
97 [info] Packaging /home/josh/projects/typesafe/scala-arm/target/scala-2.9.1/scala-arm_2.9.1-1.2.jar ...
98 [info] Wrote /home/josh/projects/typesafe/scala-arm/target/scala-2.9.1/scala-arm_2.9.1-1.2.pom
99 [info] Packaging /home/josh/projects/typesafe/scala-arm/target/scala-2.9.1/scala-arm_2.9.1-1.2-javadoc.jar ...
100 [info] Packaging /home/josh/projects/typesafe/scala-arm/target/scala-2.9.1/scala-arm_2.9.1-1.2-sources.jar ...
101 [info] :: delivering :: com.jsuereth#scala-arm_2.9.1;1.2 :: 1.2 :: release :: Mon Jan 23 13:16:57 EST 2012
102 [info] Done packaging.
103 [info] Done packaging.
104 [info] Done packaging.
105 [info] delivering ivy file to /home/josh/projects/typesafe/scala-arm/target/scala-2.9.1/ivy-1.2.xml
106 [info] published scala-arm_2.9.1 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/jsuereth/scala-arm_2.9.1/1.2/scala-arm_2.9.1-1.2-sources.jar
107 [info] published scala-arm_2.9.1 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/jsuereth/scala-arm_2.9.1/1.2/scala-arm_2.9.1-1.2-javadoc.jar.asc
108 [info] published scala-arm_2.9.1 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/jsuereth/scala-arm_2.9.1/1.2/scala-arm_2.9.1-1.2-sources.jar.asc
109 [info] published scala-arm_2.9.1 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/jsuereth/scala-arm_2.9.1/1.2/scala-arm_2.9.1-1.2.jar
110 [info] published scala-arm_2.9.1 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/jsuereth/scala-arm_2.9.1/1.2/scala-arm_2.9.1-1.2.jar.asc
111 [info] published scala-arm_2.9.1 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/jsuereth/scala-arm_2.9.1/1.2/scala-arm_2.9.1-1.2.pom.asc
112 [info] published scala-arm_2.9.1 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/jsuereth/scala-arm_2.9.1/1.2/scala-arm_2.9.1-1.2.pom
113 [info] published scala-arm_2.9.1 to https://oss.sonatype.org/service/local/staging/deploy/maven2/com/jsuereth/scala-arm_2.9.1/1.2/scala-arm_2.9.1-1.2-javadoc.jar
114 [success] Total time: 9 s, completed Jan 23, 2012 1:17:03 PM
115
116
117
c0c4dcb @jsuereth Adding missing docs.
jsuereth authored
118 After publishing you have to follow the [Release workflow of nexus](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide#SonatypeOSSMavenRepositoryUsageGuide-8.ReleaseIt). In the future, we hope to provide a Nexus SBT plugin that allows the release workflow procedures to be performed directly from SBT.
119
120 *Note: Staged releases allow testing across large projects of independent releases before pushing the full project.*
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
121
174b969 @Sciss Update src/jekyll/using_sonatype.md
Sciss authored
122 <sub>*Note:* An error message of `PGPException: checksum mismatch at 0 of 20` indicates that you got the passphrase wrong. We have found at least on OS X that there may be issues with characters outside the 7-bit ASCII range (e.g. Umlauts). If you are absolutely sure that you typed the right phrase and the error doesn't disappear, try changing the passphrase.</sub>
123
5fff0f4 @janm399 Update src/jekyll/using_sonatype.md
janm399 authored
124 ## Summary ##
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
125
5fff0f4 @janm399 Update src/jekyll/using_sonatype.md
janm399 authored
126 To get your project hosted on Sonatype (and Maven Central), you will need to:
55dc73b @jsuereth Creating help documentation for publishing to Sonatype's OSSRH
jsuereth authored
127
5fff0f4 @janm399 Update src/jekyll/using_sonatype.md
janm399 authored
128 * Have GPG key pair, with published public key,
129 * A SBT file with your Sonatype credentials *that is not pushed to the VCS*,
130 * Modify `project/plugins.sbt` to include the `xsbt-gpg-plugin` to sign the artefacts,
131 * Modify `build.sbt` with the required elements in the generated POM.
132
133 Starting with a project that is not being published, you'll need to install GPG, generate and publish your key. Swtiching to SBT,
134 you'll then need to:
135
136 #### ~/.sbt/sonatype.sbt
137
138 This file (kept *outside the VCS*) contains the Sonatype credentials settings:
139
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
140 credentials += Credentials("Sonatype Nexus Repository Manager",
141 "oss.sonatype.org",
142 "your-sonatype-username",
143 "your-sonatype-password")
5fff0f4 @janm399 Update src/jekyll/using_sonatype.md
janm399 authored
144
145 #### project/plugins.sbt
146
147 This file specifies the plugins for your project. If you intend to sign the artefacts, you'll need to include @jsuereth's `xsbt-gpg-plugin`:
148
b5b1d53 @jrudolph Fix plugin resolver to use ivyStylePatterns, won't work otherwise.
jrudolph authored
149 resolvers += Resolver.url("sbt-plugin-releases", /* no new line */
150 new URL("http://scalasbt.artifactoryonline.com/scalasbt/sbt-plugin-releases")) /* no new line */
151 (Resolver.ivyStylePatterns)
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
152
153 addSbtPlugin("com.jsuereth" % "xsbt-gpg-plugin" % "0.5")
5fff0f4 @janm399 Update src/jekyll/using_sonatype.md
janm399 authored
154
155 #### build.sbt
156
157 Finally, you'll need to tweak the generated POM in your `build.sbt`. The tweaks include specifying the project's authors, URL, SCM and many others:
158
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
159 publishTo <<= version { v: String =>
160 val nexus = "https://oss.sonatype.org/"
161 if (v.trim.endsWith("SNAPSHOT")) Some("snapshots" at nexus + "content/repositories/snapshots")
162 else Some("releases" at nexus + "service/local/staging/deploy/maven2")
163 }
164
165 publishMavenStyle := true
166
167 publishArtifact in Test := false
168
174b969 @Sciss Update src/jekyll/using_sonatype.md
Sciss authored
169 pomIncludeRepository := { _ => false }
2bc13ed @jsuereth Fixed syntax to work with Jekyll/liquid
jsuereth authored
170
171 pomExtra := (
172 <url>http://your.project.url</url>
173 <licenses>
174 <license>
175 <name>BSD-style</name>
176 <url>http://www.opensource.org/licenses/bsd-license.php</url>
177 <distribution>repo</distribution>
178 </license>
179 </licenses>
180 <scm>
181 <url>git@github.com:your-account/your-project.git</url>
182 <connection>scm:git:git@github.com:your-account/your-project.git</connection>
183 </scm>
184 <developers>
185 <developer>
186 <id>you</id>
187 <name>Your Name</name>
188 <url>http://your.url</url>
189 </developer>
190 </developers>
191 )
Something went wrong with that request. Please try again.