Installing Scala Packages from GitHub's Registry

A short guide for installing Scala packages from GitHub's Apache Maven package registry.

Table of contents

1. Tools
2. Prerequisites
   1. Generating a token
3. Installation
4. Token Options
   1. Environment
   2. Configuration

Tools

• SBT
• GitHub

Prerequisites

Installing packages from GitHub's package registry requires a personal access token.

Generating a token

1. Visit your Settings > Developer Settings > Personal access tokens > Tokens (classic)
2. Generate new token (classic) under the Generate new token drop-down menu
3. Enable the permission for read:packages under write:packages. This permission is the minimum requirement to install packages.
4. Save your token somewhere safe and have it ready.

Installation

1. In your Scala project, ensure it is built with SBT
2. Visit the build.sbt file containing the project's semantics.
3. Add a credentials field which will contain your token. The Credentials type uses a realm, host, username, and password.
   • You are not required to have a non-empty string in the field, therefore you may give it an empty string.
   • The passwd argument will contain your token.
     • Explore other ways to store and get your token

credentials += Credentials(
    realm = "GitHub Package Registry",
    host = "maven.pkg.github.com",
    userName = "",
    passwd = "YOUR_TOKEN_HERE"
)

4. Add a resolver with the package maintainer's name and name of the repository.

resolvers += "GitHub Package Registry (MAINTAINER/PACKAGE_REPOSITORY)" at
    "https://maven.pkg.github.com/MAINTAINER/PACKAGE_REPOSITORY"

5. Specify the library dependency.

libraryDependencies += "org.example" %% "example" % "1.0.0"

6. Load your SBT changes and you should have the package(s) installed.

The build.sbt file should at least contain the following contents. This example is for one package.

ThisBuild / version := "1.0.0"
ThisBuild / scalaVersion := "3.3.1"

credentials += Credentials(
    realm = "GitHub Package Registry",
    host = "maven.pkg.github.com",
    userName = "",
    passwd = sys.env.getOrElse("GITHUB_TOKEN", "")
)

resolvers += "GitHub Package Registry (MAINTAINER/PACKAGE_REPOSITORY)" at 
    "https://maven.pkg.github.com/MAINTAINER/PACKAGE_REPOSITORY"
    
libraryDependencies += "org.example" %% "example" % "1.0.0"

Token Options

Environment

The token may also be obtained from the environment. Set an environment variable such as GITHUB_TOKEN and fetch it. This also works with GitHub actions since it has a GITHUB_TOKEN environment variable with your token.

// Using the System class
System.getenv("GITHUB_TOKEN")

// Using Scala's sys package
sys.env.getOrElse("GITHUB_TOKEN", "")
// This also works but will throw an error if there is no such environment variable
sys.env("GITHUB_TOKEN")

Configuration

Another method is going through the git config. In your .gitconfig file, define a key with your token as the value.

[github]
  token = "YOUR_TOKEN_HERE"

Then in the sbt file, import scala.sys.process.Process and use it to run git config github.token, and obtain your token. (It's also possible to use the global config by passing in --global otherwise it defaults to --local)

// Gets the output of running the git command for your token
Process.apply("git config github.token").!!