scala-project-bootstrap.md

Easy Scala Publication

The following describes how you can publish artifacts for any sbt project using the GitHub Package Registry and the sbt-github-packages plugin.

Step 1: Create a GitHub Token

In your GitHub account, go to Settings > Developer settings > Personal access tokens, then click on Generate new token (or click here). Fill in some sort of meaningful name (I chose Dev) and click on the write:packages checkbox:

Now scroll down and click Generate token. You should be taken back to the token management page, where you will see something that looks a bit like this:

Copy the hexadecimal value shown within the green banner (or click on the clipboard button to the right). If you miss this step, you'll need to re-generate the token as there is no way to reveal its contents once created! Save the token contents in a local file, or proceed directly to Step 2.

Step 2: Configure Your Environment

Open up your shell and run the following commands:

$ git config --global github.user USERNAME
$ git config --global github.token PASTE

Replace USERNAME with your GitHub user. Replace PASTE with the contents of your clipboard from Step 1.

Step 3: Configure Your Project

In your sbt project, add the following text to your project/plugins.sbt file:

addSbtPlugin("com.codecommit" % "sbt-github-packages" % "0.2.1")

Save that, and then edit your build.sbt file, adding the following lines at the very bottom:

ThisBuild / githubOwner := "OWNER"
ThisBuild / githubRepository := "REPOSITORY"

ThisBuild / githubTokenSource := Some(TokenSource.GitConfig("user.token"))

Replace OWNER with the GitHub user or organization which hosts your repository (e.g. it may be the same as your USERNAME from earlier!). Replace REPOSITORY with the name of your GitHub repository. This could just be the name of your project. The githubTokenSource line is correct exactly as-written, though you are of course free to do different things if you do not wish to store a GitHub token using git config.

(Optional) Step 4: Add sbt-gpg

Add the following text to your project/plugins.sbt file:

addSbtPlugin("io.crashbox" % "sbt-gpg" % "0.2.1")

You do not need to do this, it's just generally best practice. If you add this line, you will also need to make sure you have GnuPG installed and a private key with signing capabilities correctly generated. If you don't know what any of this is, just skip this step.

Step 5: Publish!

You can now run sbt publish on your project! The results will be pushed to the GitHub Package Registry for your project. You can view this in the browser by visiting https://github.com/OWNER/REPOSITORY/packages, replacing OWNER and REPOSITORY with the same values you used earlier.

Step 6: Add as a Dependency

Anyone can now use your published artifacts within their projects by adding the sbt-github-packages plugin to their project/plugins.sbt file:

addSbtPlugin("com.codecommit" % "sbt-github-packages" % "0.2.1")

And then, within their build.sbt, adding the following line:

resolvers += Resolver.githubPackagesRepo("OWNER", "REPOSITORY")

Replacing OWNER and REPOSITORY with the information you used when you published the package. Note that these steps work even if you published to a private repository, though the downstream user will also need to perform steps 1 and 2 from above, as well as adding the githubTokenSource line to their build.sbt as described (so as to properly authenticate their download requests).

Once these steps are taken, downstream users can declare a dependency on your published artifacts in the normal fashion, adding the artifact identifier to the libraryDependencies setting within their projects!