Publish Android libs to Nexus
Creating a great library is hard work. Coming up with the idea, implementing it, making sure you have a nice, stable public API that you control carefully and maintain… That’s already lots to do.
After all that, you need to make your library available to the public. Technically, you could distribute the .aar file any way you want, but the norm is publishing it to a publicly available Maven repository. It’s a good idea to use one of the well-established repositories that people are already likely to have in their projects, to make getting started with your library as easy as possible.
The fanciest place you can be in is The Central Repository via Sonatype OSSRH (OSS Repository Hosting), which I’ll refer to as simply MavenCentral from here on. This is the place to be if you’re a Maven dependency. Artifacts on MavenCentral are well trusted, and their integrity can be verified, as they are all required to be signed by the author.
The simplest choice would be JitPack, which might not give you much in terms of customization or control, but is very easy to get started with. All you have to do is publish your project on GitHub, and JitPack should be able to build and distribute it immediately. If you’re new to libraries, this is a great choice for getting your code out there.
I try to use JitPack but failed to config. If you success to use JitPack in the Android SDK for Stream Chat, please let me know. Thanks.
Overview
Here's a quick overview of the steps we'll go through:
- Registering a Jira account with Sonatype, and verifying your ownership of the group ID you want to publish your artifact with
- Generating a GPG key pair for signing your artifacts, publishing your public key, and exporting your private key
- Setting up Gradle tasks that can sign upload your artifacts to a staging repository
- Manually going through the process of checking your artifacts in the staging repo and releasing them via the Sonatype web UI
- Automating the close & release flow with a Gradle plugin
- Configuring CI workflows with GitHub Actions to automate all of the above A lot of ground to cover - let’s go!
Prerequisites
We’ll be using the following tools for this tutorial. You are free to use alternatives, but these are our favourites, and they work well for us.
- GitHub as the public host of the library’s repository
- Registering a Sonatype account
- The command line gpg tool
For this article, we’ll assume that you already have your library developed, and have uploaded it to a public GitHub repository. We’ll use our very own Android Chat SDK in our examples. This SDK is made up of multiple artifacts, but for simplification, we’ll just talk about publishing the low-level networking client, which lives in the stream-chat-android-client module of the GitHub repository.
Registering a Sonatype account
First things first, you’ll need an account in the Sonatype Jira. Head over there and hit Sign up. Registration is straightforward, it just requires a username, an email, and a password. After you’ve logged in, you’ll need to open an issue, asking for access to the group ID that you’ll want to publish your project under. For us, based on our domain name (gitcoins.io), our group ID is io.gitcoins. If you own a domain, it’s best to choose the reversed version of that as your group ID. Otherwise, you’ll have to stick with having a GitHub-based group ID.
After choosing a language and an avatar, you’ll end up on this landing page - click on Create an issue
- Summary: Create repository for your.group.id.here
- Description: An optional, quick summary of what your project is.
- Group Id: Your group ID, as described a few sections earlier.
- Project URL: If your project has a webpage, the URL of that page. This can also be just the GitHub repository.
- SCM url: Your source control URL, i.e. the GitHub repository link.
- Username(s): If you want additional users (on top of the one you’re using for this process) to have deploy access for your group ID, you can list them here.
- Already Synced to Central: If you’re just getting started, this should be No.
Soon after opening it, your issue will get a comment telling you to verify that you own the domain corresponding to your group ID. To comply with this, add the required TXT record to your domain - how to do this will depend on where your domain is registered, but it should be a fairly simple task. Login to the goDaddy to set the TXT record with the guide from the issue created in jira for Sonatype.
Generating a GPG key pair
As we eluded to earlier, artifacts published on MavenCentral have to be signed by their publishers. You’ll need a GPG key for this.
MavenCentral also has its own documentation for Working with PGP Signatures which you can reference if you get stuck along the way.
This part requires access to the gpg command. There are several ways to install this via package managers, and there are many distributions available for different platforms on gnupg.org.
We'll stick to the command line here on Linux for generating and managing keys.
To generate a new key, run the following command:
gpg --full-gen-key
You’ll be prompted to enter a few details:
- Kind of key: Accept the default value, which is (1) RSA and RSA.
- Key size: 4096.
- Expiration: You can input 0 to generate a key that never expires. You can also create a key that has an expiry date and then renew it periodically, if you prefer to do so.
- Real name, email: Should be obvious.
- Comment: Freeform text, can be left empty. After entering these details, you’ll be prompted to enter a passphrase to secure your key with.
Here’s the full flow you'll go through, with a bit of truncation:
Please select what kind of key you want:
(1) RSA and RSA (default)
...
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
0 = key does not expire
...
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y
GnuPG needs to construct a user ID to identify your key.
Real name: Marton Braun
Email address: [email protected]
Comment: Example key for tutorial
You selected this USER-ID:
"Marton Braun (Example key for tutorial) <[email protected]>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
gpg: key 36271B955BEF072A marked as ultimately trusted
gpg: revocation certificate stored as '.../gnupg/openpgp-revocs.d\7A5D73CFEDDDBC915986998A36271B955BEF072A.rev'
public and secret key created and signed.
pub rsa4096 2024-02-03 [SC]
7A5D73CFEDDDBC915986998A36271B955BEF072A
uid Marton Braun (Example key for tutorial) <[email protected]>
sub rsa4096 2024-02-03 [E]
You can always check the keys you have on your system by running gpg --list-keys:
gpg --list-keys
gpg: checking the trustdb
.../gnupg/pubring.kbx
-----------------------------------------------
pub rsa4096 2021-02-03 [SC]
7A5D73CFEDDDBC915986998A36271B955BEF072A
uid [ultimate] Marton Braun (Example key for tutorial) <[email protected]>
sub rsa4096 2021-02-03 [E]
Your key’s ID is the last eight digits of its fingerprint (the long hexadecimal string above). In this case, this is 5BEF072A - take note of this, as you’ll use this later.
You’ve generated a pair of keys - a private and a public key. You’ll keep the private one hidden and use it to sign your artifacts. The public key has to be uploaded to the server so that anyone can check that it belongs to you, which you can do by running the following (use your own key ID!):
gpg --keyserver keyserver.ubuntu.com --send-keys 5BEF072A
Your private key will need to be referenced by your project when it signs the artifacts. You can get a base 64 export of it with the following:
gpg --export-secret-keys 5BEF072A | base64
Setting up publication in your project
That’s a lot of work without touching your project, but the time has come to do that now. In the next few steps, you will:
- Add Gradle scripts that set up the publication plugin required to push artifacts to a repository.
- Configure the properties of the library you’re releasing.
- Grab the necessary authentication details along with the private key you’ve just exported.
Five variables will be used to sign and publish the artifacts after they’re built:
- signing.keyId: the ID of the GPG key pair, the last eight characters of its fingerprint
- signing.password: the passphrase of the key pair
- signing.key: Generate gpg key with command
gpg --export-secret-keys --armor F207B5A1 > my.gpg. F207B5A1 is last 8 characters in the public key, you can get public key by gpg --list-keys - osshrUsername and ossrhPassword: This is the token username and password, not the one used for logging into the UI. MavenCentral Token
- sonatypeStagingProfileId: Go to https://s01.oss.sonatype.org/ and log in. In the menu on the left, select Staging profiles, select your profile, and then look for the ID in the URL. The 638cedd9d39c2 is the sonatypeStagingProfileId.
Root project Gradle configuration
To easily automate publishing later, you'll use the gradle-nexus/publish-plugin tool. This has to be added in your project level (root) build.gradle file as a dependency.
You can do this either with a plugins block:
apply plugin: 'io.github.gradle-nexus.publish-plugin'
buildscript {
repositories {
...
mavenCentral()
}
dependencies {
...
classpath Dependencies.gradleNexusPublishPlugin
}
}
Publishing configuration
Next, create a new file called publish-root.gradle in a new scripts folder inside your project. This will contain global configuration you need for publishing, grabbing input values for your scripts, and defining the MavenCentral repository.
import io.getstream.chat.android.Configuration
// Create variables with empty default values
ext["ossrhUsername"] = ''
ext["ossrhPassword"] = ''
ext["sonatypeStagingProfileId"] = ''
ext["signing.keyId"] = ''
ext["signing.password"] = ''
ext["signing.key"] = ''
ext["snapshot"] = ''
File secretPropsFile = project.rootProject.file('local.properties')
if (secretPropsFile.exists()) {
// Read local.properties file first if it exists
Properties p = new Properties()
new FileInputStream(secretPropsFile).withCloseable { is -> p.load(is) }
p.each { name, value -> ext[name] = value }
} else {
// Use system environment variables
ext["ossrhUsername"] = System.getenv('OSSRH_TOKEN_USERNAME')
ext["ossrhPassword"] = System.getenv('OSSRH_TOKEN_PASSWORD')
ext["sonatypeStagingProfileId"] = System.getenv('SONATYPE_STAGING_PROFILE_ID')
ext["signing.keyId"] = System.getenv('SIGNING_KEY_ID')
ext["signing.password"] = System.getenv('SIGNING_PASSWORD')
ext["signing.key"] = System.getenv('SIGNING_KEY')
ext["snapshot"] = System.getenv('SNAPSHOT')
}
if (snapshot) {
ext["rootVersionName"] = Configuration.snapshotVersionName
} else {
ext["rootVersionName"] = Configuration.versionName
}
// The following makes the key available for publishing to Nexus
// OSSRH_TOKEN_USERNAME: ${{ secrets.OSSRH_TOKEN_USERNAME }}
// OSSRH_TOKEN_PASSWORD: ${{ secrets.OSSRH_TOKEN_PASSWORD }}
// SONATYPE_STAGING_PROFILE_ID: ${{ secrets.SONATYPE_STAGING_PROFILE_ID }}
// After making the github action secrets above available, you can try publish in the github workflow
// ./gradlew publishToSonatype
// ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository
nexusPublishing {
repositories {
//sonatype()
sonatype {
nexusUrl.set(uri("https://s01.oss.sonatype.org/service/local/"))
snapshotRepositoryUrl.set(uri("https://s01.oss.sonatype.org/content/repositories/snapshots/"))
version = rootVersionName
stagingProfileId = sonatypeStagingProfileId
username = ossrhUsername
password = ossrhPassword
}
}
// these are not strictly required. The default timeouts are set to 1 minute. But Sonatype can be really slow.
// If you get the error "java.net.SocketTimeoutException: timeout", these lines will help.
connectTimeout = Duration.ofMinutes(3)
clientTimeout = Duration.ofMinutes(3)
}
tasks.withType(dokkaHtmlMultiModule.getClass()) {
includes.from("DokkaRoot.md")
}
If you're on the new Sonatype infrastructure (happens if you've registered after 2021-02-24 or requested it specifically), you have to add explicit URLs pointing to s01.oss.sonatype.org in this config block next to the existing parameters
Release configuration
You’ll set two properties on the Gradle project itself here, the group ID and the version of the artifact. You’ll see where these uppercase values come from later on, when you apply this publication script in the module level build.gradle files.
apply plugin: 'maven-publish'
apply plugin: 'signing'
apply plugin: 'org.jetbrains.dokka'
tasks.register('androidSourcesJar', Jar) {
archiveClassifier.set('sources')
if (project.plugins.findPlugin("com.android.library")) {
from android.sourceSets.main.java.srcDirs
from android.sourceSets.main.kotlin.srcDirs
} else {
from sourceSets.main.java.srcDirs
from sourceSets.main.kotlin.srcDirs
}
}
tasks.withType(dokkaHtmlPartial.getClass()).configureEach {
pluginsMapConfiguration.set(
["org.jetbrains.dokka.base.DokkaBase": """{ "separateInheritedMembers": true}"""]
)
}
task javadocJar(type: Jar, dependsOn: dokkaJavadoc) {
archiveClassifier.set('javadoc')
from dokkaJavadoc.outputDirectory
}
artifacts {
archives androidSourcesJar
archives javadocJar
}
group = PUBLISH_GROUP_ID
version = PUBLISH_VERSION
afterEvaluate {
publishing {
publications {
release(MavenPublication) {
tasks.named("generateMetadataFileForReleasePublication").configure { dependsOn("androidSourcesJar") }
groupId PUBLISH_GROUP_ID
artifactId PUBLISH_ARTIFACT_ID
version PUBLISH_VERSION
if (project.plugins.findPlugin("com.android.library")) {
from components.release
} else {
from components.java
}
artifact javadocJar
pom {
name = PUBLISH_ARTIFACT_ID
description = 'Stream Chat official Android SDK'
url = 'https://github.com/thebestornothing/stream-chat-android'
licenses {
license {
name = 'Stream License'
url = 'https://github.com/thebestornothing/stream-chat-android/blob/main/LICENSE'
}
}
developers {
developer {
id = 'leandroBorgesFerreira'
name = 'Leandro Borges Ferreira'
email = '[email protected]'
}
developer {
id = 'bychkovdmitry'
name = 'Dmitrii Bychkov'
email = '[email protected]'
}
}
scm {
connection = 'scm:git:github.com/thebestornothing/stream-chat-android.git'
developerConnection = 'scm:git:ssh://github.com/thebestornothing/stream-chat-android.git'
url = 'https://github.com/thebestornothing/stream-chat-android/tree/main'
}
}
}
}
}
}
// For signing you need to make signingKey and signingPassword available properties
// SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
// SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
// After making the github action secrets above available, you can try publish in the github workflow
// ./gradlew signMavenPublication
//
def hasSigningKey = rootProject.ext["signing.keyId"] || rootProject.ext["signing.key"]
if(hasSigningKey) {
sign(project)
}
void sign(Project project) {
project.signing {
required { project.gradle.taskGraph.hasTask("publish") }
def signingKeyId = rootProject.ext["signing.keyId"]
def signingKey = rootProject.ext["signing.key"]
def signingPassword = rootProject.ext["signing.password"]
if (signingKeyId) {
useInMemoryPgpKeys(signingKeyId, signingKey, signingPassword)
} else if (signingKey) {
useInMemoryPgpKeys(signingKey, signingPassword)
}
sign publishing.publications
}
}
Version configuraiton
Finally see the group ID, artifact ID, and version being set, so that the publication script can make use of them. Then, the script itself is applied. This is all the code you need to add per-module if you are publishing your library in multiple artifacts, everything else is done by the common script.
object Configuration {
const val compileSdk = 34
const val targetSdk = 34
const val sampleTargetSdk = 34
const val minSdk = 21
const val majorVersion = 6
const val minorVersion = 0
const val patchVersion = 8
const val myVersion = 2
const val versionName = "$majorVersion.$minorVersion.$patchVersion.$myVersion"
const val snapshotVersionName = "$majorVersion.$minorVersion.${patchVersion + 1}-SNAPSHOT"
const val artifactGroup = "io.gitcoins"
}
Github Action integration
Since the library is hosted on GitHub anyway, we use GitHub Actions for running the publication Gradle tasks automatically. Whatever CI solution you’re using, setting up publication with it will consist of two main steps:
- Getting your secret variables in place.
- Invoking the two Gradle tasks.
Your secret variables - for the list of these, look at the publishing script again - can simply go into Repository secrets (Add each of these by going to Settings -> Secrets within your GitHub repository). All the variables will be show in the Actions secrets and variables.
Now, let’s create the GitHub Actions workflow that will put all of this together. The configuration for this will go in the .github/workflows/publish.yml file of the repository. This publish workflow will run every time a new release is created in the repository (you can also change the triggers to run when a tag is created, for example).
name: PublishGitcoins
on:
push:
tags:
- '[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+'
jobs:
publish:
name: Release build and publish beta
runs-on: ubuntu-22.04
steps:
- name: Check out code
uses: actions/checkout@v3.1.0
- name: Set up JDK 17
uses: actions/setup-java@v3.6.0
with:
distribution: adopt
java-version: 17
- name: Release build
# assembleRelease for all modules, excluding non-library modules: samples, docs
run: ./gradlew assembleRelease -x :stream-chat-android-ui-components-sample:assembleRelease -x :stream-chat-android-compose-sample:assembleRelease -x :stream-chat-android-docs:assembleRelease
- name: Source jar and dokka
run: ./gradlew androidSourcesJar javadocJar
- name: Publish to MavenCentral
run: ./gradlew publishReleasePublicationToSonatypeRepository --max-workers 1 closeAndReleaseSonatypeStagingRepository
env:
OSSRH_TOKEN_USERNAME: ${{ secrets.OSSRH_TOKEN_USERNAME }}
OSSRH_TOKEN_PASSWORD: ${{ secrets.OSSRH_TOKEN_PASSWORD }}
SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
SONATYPE_STAGING_PROFILE_ID: ${{ secrets.SONATYPE_STAGING_PROFILE_ID }}
Your first release
After adapt the code of stream-chat-android and create new tag like v6.0.8-beta16, the workflow action will be triggered.
git tag -a v6.0.8-beta16 -m "v6.0.8.2 publish"
git push origin v6.0.8-beta16
Go to action page in the repository, lookup the detailed info in the running workflow. After the workflow run successfully, go to the Nexus Repository Manager and in the menu on the left, select Staging repositories.Search or find your repository (search gitcoins in the Artifact Search), which has your group ID in its name. If you select it and look at the Content tab, you’ll see the files that have been published.
Using the publish library
Create new Project in Android studio
To get started with the Jetpack Compose version of the Android Chat SDK, open Android Studio (Giraffe or newer) and create a new project.
- Select the Empty Activity template
- Name the project ChatTutorial
- Set the package name to com.example.chattutorial
Add Stream Chat Compose SDK
Let's add the Stream Chat Compose SDK to the project's dependencies. io.gitcoins:stream-chat-android-compose:6.0.8.2 and io.gitcoins:stream-chat-android-offline:6.0.8.2 are coming from Nexus Repository which have been published according to this guide.
dependencies {
implementation("io.gitcoins:stream-chat-android-compose:6.0.8.2")
implementation("io.gitcoins:stream-chat-android-ui-utils:6.0.8.2")
implementation("io.gitcoins:stream-chat-android-offline:6.0.8.2")
//implementation("io.getstream:stream-chat-android-compose:6.0.8")
//implementation("io.getstream:stream-chat-android-offline:6.0.8")
}