Publish Your First Package With Gradle and GitLab

We are approaching the holiday season and, if you somehow celebrate, you will likely have to think thoroughly about this year’s round of gifts and how to delight family and friends. I admit, I sometimes feel that consumerism has spoiled a little the innocence of the gifting ritual. At the very least, I feel that I should personally wrap my gift boxes to give them a personal touch and earn back the joy of donating something.

If we can take care of the physical envelopes of our gifts, why not learn how to do the same with marvelous software packages to share with our team? After all, it is renowned that we should maximize code reuse to speed up development and, most importantly, to make our coworkers' life easier.

If your team collaborates on GitLab and is keen on building Gradle projects, this is the time of learning the respectable craft of package publishing.

Prerequisites

Before committing to our box-wrapping task, please make sure that you have all the required materials on hand:

Gradle v7.2.0+ (if you are on v6 you can still follow along, just look out for specific notes)
Maintainer access to a GitLab project or group
A fantastic API library to share with your team

Set up a project

If you already have a clear idea of which project to put in your package, just skip this section and go on to choose some fancy ribbon.

However, if you are starting from scratch, navigate to a new directory and submit the command gradle init into your command line of preference. Then, when prompted for a project type, select 3. library. Complete the initial configuration with the settings that best apply to the project. For this guide, I generated a library in the Kotlin language with a Groovy DSL build script (and yes, it is on GitLab and you can browse it here).

Finally, you may also want to set up a new GitLab project to host the library source code and its package artifacts.

Authenticate to the Package Repository

When it comes to publishing private packages, GitLab allows for a few different authorization methods:

personal access token
deploy token
CI_JOB_TOKEN

A personal access token is linked to a specific account, so you probably shouldn’t share it with your team. On the other hand, a CI_JOB_TOKEN is generally used in CI/CD pipelines, so you may not be interested in them just yet since we will publish our library manually in this article.

For our use case, a deploy token seems like the best option. To generate a token, navigate to the desired GitLab group or project (the maintainer role is required), then browse Settings>Repository and expand the Deploy Tokens section. Choose a name, expiry date (optional), and username (optional) for the token and assign read_package_registry, write_package_registry scopes.

Make sure you assign the correct scopes when creating your token

Finally, push the satisfying Create deploy token blue button and store the result safely, as the newly generated token can not be accessed again.

Now you can connect your library to the Package Repository. Simply add a publishing section in the build.gradle script and enable the publishing plugin.

Don’t forget to enable the publish plugin:

Replace the PROJECT_ID placeholder with the project ID as shown in the GitLab repository, under the project name.

A note about earlier Gradle versions

The layout for the publishing section was slightly different in earlier versions of Gradle, as shown in the code snippet below:

Publish

Run the task gradle publish. The packaged libraries can be browsed in the Packages & Registries page of the selected project and can be now downloaded by external projects.

The project’s Package Registry featuring multiple versions

Remember to properly update the version field in the build.gradle file to keep track of all your changes.

Import a Package

A published Packaged can be imported as a dependency into a project. However, it is necessary to update the repository section in the build.gradle for the project that relies on the dependency:

To import the library update the project dependencies:

Conclusion

I hope that you enjoyed dirtying your hands with colorful wrapping papers and flashy bows.

Just remember: of course it’s the thought that counts but please keep any squishy bug out of your package!

CHRISTMAS — Photo by Chang Duong / Unsplash

References

GitLab repository: https://gitlab.com/loris.occhipinti2/kotlin-library-tutorial
Official docs: https://docs.gitlab.com/ee/user/packages/maven_repository/index.html