er1c / sbt-github   0.2.0

Forking/refactoring sbt-bintray for GitHub support

• Requirements: sbt 1.2.1 or later.

See remote caching for information about sbt-github-remote-cache.

resolvers +=  "sbt-github-releases" at "https://maven.pkg.github.com/er1c/sbt-github"
credentials += Credentials("GitHub Package Registry", "maven.pkg.github.com", "<github-user>", "<GITHUB_TOKEN>")

If you want to publish to GitHub, read on.

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

addSbtPlugin("io.github.er1c" % "sbt-github" % "0.2.0")

Note that when specifying sbt-github settings in project/*.scala files (as opposed to in build.sbt), you will need to add the following import:

import github.GitHubPluginKeys._

ThisBuild / githubOwner := "er1c"
ThisBuild / githubOwnerType := GitHubOwnerType.User
ThisBuild / githubRepository := "sbt-github"

ThisBuild / githubOwner := "sbt"
ThisBuild / githubOwnerType := GitHubOwnerType.Organization
ThisBuild / githubRepository := "io"

To publish a package to github, you need a github account. You can register for one here. GitHubPlugin is an auto plugin that will be added to all projects in your build. This plugin will upload and release your artifacts into github when you run publish.

To exclude a project from being published (for example a root or a tests project) use the skip setting:

publish / skip := true

At any time you can check who you will be authenticated as with the githubWhoami setting which will print your github username

> githubWhoami

To publish, you need to provide github credentials (user name and API key). There are three ways to set them up: credential file, properties, and environment variables.

1. Credentials file

sbt-github will look for a credentials file under ~/.github/.credentials used to authenticate publishing requests to github.

realm = GitHub API Realm
host = api.github.com
user = <github user>
password = <api_token>

You can interactively set up or change the github credentials used by sbt anytime with

> githubChangeCredentials

Note you will need to reload your project afterwards which will reset your publishTo setting.

2. Properties

You can pass the user and pass as JVM properties when starting sbt:

sbt -Dgithub.user=yourgithubUser -Dgithub.pass=yourgithubPass

3. Environment variables

sbt-github will look for github user and pass in the environment variables github_USER and github_PASS.

You may optionally wish to publish to a github organization instead of your individual github user account. To do so, use the githubOrganization setting in your project's build definition.

githubOwner := Some("strength-in-numbers")
githubOwnerType := GitHubOwnerType.Organization

The default GitHub repository, for a github user or organization is named maven. If your Maven repository is named differently, you will need to specify the githubRepository setting.

githubRepository := "oss-maven"

If your project uses a license, github supports several OSS licenses. If you are new to software licenses you may want to grab a coffee and absorb some well organized information on the topic of choice. Sbt already defines a licenses setting key. In order to use github sbt you must define your licenses key to contain a license with a name matching one of those github defines. I recommend MIT.

licenses += ("MIT", url("http://opensource.org/licenses/MIT"))

It's generally a bad practice to remove a version of a library others may depend on but sometimes you may want test a release with the ability to immediately take it back down if something goes south before others start depending on it. github allows for this flexibility and thus, sbt-github does as well. Use the unpublish task to unpublish the current version from github.

> githubUnpublish

The easiest way to learn about sbt-github is to use the sbt shell typing github<tab> or help github to discover github keys.

This plugin was first created by Doug Tangren (softprops), 2013-2014.

The plugin is now maintained by er1c.