Library Photo by Alfons Morales on Unsplash

Using Kotlin DSL to publish an Android library to GitHub Packages

GitHub has recently introduced the GitHub Packages, a package management service where developers and organizations can publish packages either publicly for the open-source community or privately for use within an organization.

GitHub Packages allows you to host libraries or packages, which can be reused by different projects.

GitHub packages is available free for public repositories and with a pay-as-you-go pricing model for private repositories. More information can be found at the below link:

About GitHub Packages

In this article specifically aimed at Android Developers, we look into steps on how we can use Github packages to host an Android Library (Android Archive (AAR) file) that can be used as a dependency on various android projects.

I had previously discussed on using Groovy to write a Gradle script to publish an Android Library to GitHub Packages. In this article, we focus on modifying the Gradle script to use Kotlin DSL to publish Android libraries.

NOTE: A prerequisite for this article is that your Android Project should already be migrated and using Kotlin DSL build scripts. Do make sure to read some guides on migrating to Kotlin DSL. Also understand the pros and cons of migrating to Kotlin DSL before using it in production code. Android Studio IDE already supports Kotlin DSL.

There are 2 parts to this article. In Part 1 we discuss about publishing a library file onto GitHub packages and in Part 2 we follow steps to use a library from GitHub packages.

Part 1 — Publish an Android library to GitHub Packages

Step 1: Generate a Personal Access Token for GitHub

• From within your GitHub account:
• Settings -> Developer Settings -> Personal Access Tokens -> Generate new token
• Make sure you select the following scopes (“ write:packages”, “ read:packages”) and Generate a token

Generate Personal Access Token : Select scopes

• After Generating make sure to copy your new personal access token. You cannot see it again! The only option is to regenerate a token or create a new key.

Step 2: Store your GitHub — Personal Access Token details

• Create a github.properties file within your root Android project
• In case of a public repository make sure you add this file to .gitignore for keeping the token private
• Add properties gpr.usr=GITHUB_USERID and gpr.key=PERSONAL_ACCESS_TOKEN
• Replace GITHUB_USERID with personal / organization Github User ID and PERSONAL_ACCESS_TOKEN with the token generated in #Step 1

Alternatively, you can also add the GPR_USER and GPR_API_KEY values to your environment variables on your local machine or build server to avoid creating a github.properties file

Step 3: Apply the ‘maven-publish’ plugin and GitHub authentication credentials to the build.gradle.kts file from the library module

The build.gradle.kts file is essentially same as the build.gradle file. The .kts extension signifies the gradle file is ready to use Kotlin.

• The ‘maven-publish’ plugin allows you to publish build artifacts to maven repositories. This plugin uses an extension ‘publishing’ which provides a container of publications and repositories.
• To apply the plugin add the following code at the beginning of build.gradle.kts file of the library module

plugins {    
   id("maven-publish")
}

• Next customise the publication metadata with your library details

groupId -> package or group ID
artifactId -> library name
version -> version of library
artifact -> the path to the artifact file (i.e. the aar file)

configure publications details

• Next, configure details related to the publishing repository and GitHub credentials

name -> "GitHubPackages"
url -> path to the repo
credentials -> authentication details required to publish to Github

configure repositories details

Step 4: Publish the Android Library onto GitHub Packages

NOTE: Make sure to build and run the tasks to generate the library files inside build/outputs/aar/ before proceeding to publish the library.

• Execute the Publish gradle task from the library module

$ gradle publish

• Once the task is successful you should be able to see the Package under the Packages tab of the GitHub Account

Published packages on GitHub Packages

• In case of a failure run the task with –stacktrace, –info or –debug to check the logs for detailed information about the causes.

NOTE: The library file (aar) will not include the transitive dependencies (i.e. dependencies used by the library).

For Maven repos, Gradle will download the dependencies using the pom file which will contain the dependencies list.

In this sample code/project, the pom file generated does not include the nested dependencies list. Either you have to specify the dependencies in your project that uses the library or you’ll have to modify the code to generate a pom file with dependencies included while building and publishing the library.

Part 2 — Using an Android library from GitHub Packages within an Android Application

NOTE: Currently the GitHub Packages require us to Authenticate to download/consume an Android Library (Public or Private) hosted on the GitHub Package. This might change for future releases.

Steps 1 and 2 are similar to Part 1 and can be skipped if already done while publishing a library

Step 1: Generate a Personal Access Token for GitHub

• Inside your GitHub account:
• Settings -> Developer Settings -> Personal Access Tokens -> Generate new token
• Make sure you select the following scopes (“ read:packages”) and Generate a token
• After Generating make sure to copy your new personal access token. You cannot see it again! The only option is to generate a new key.

Step 2: Store your GitHub — Personal Access Token details

• Create a github.properties file within your root Android project
• In case of a public repository make sure you add this file to .gitignore for keeping the token private
• Add properties gpr.usr=GITHUB_USERID and gpr.key=PERSONAL_ACCESS_TOKEN
• Replace GITHUB_USERID with personal / organization Github User ID and PERSONAL_ACCESS_TOKEN with the token generated in #Step 1

NOTE: Alternatively you can also add the GPR_USER and GPR_API_KEY values to your environment variables on you local machine or build server to avoid creating a github properties file

Step 3: Update build.gradle.kts inside the app module with the Github repository path and credentials

• configure details related to the publishing repository and GitHub credentials with the following code

configure repositories details for Github packages

• inside dependencies of the build.gradle.kts of app module, add the dependency to the library on GitHub Packages.

dependencies {
 //Use SampleAndroidLib2 library implementation("com.enefce.libraries:sampleAndroidLib2:1.0.2")
}

Sync your Android gradle project and the library from Github Packages should be synced with your Android Project and ready to use.

A sample implementation Android Project, related to this article can be found on GitHub at the below link. If you would like to use the below project to test uploading and using the library, please do send me a request and I can add you to the sample project as a collaborator.

enefce/AndroidLibrary-GPR-KDSL

Finally a big thank you and best wishes to all our readers and contributors in the developer community for the Holidays and the coming new year!