# sbt Repositories

> Use a CloudRepo Maven repository from sbt: resolvers, the credentials file or environment variables, publishTo, and what sbt prints for a 401.

sbt reads and publishes through a CloudRepo Maven repository. There is no separate sbt repository type. sbt needs three things: the repository URL, a credential whose realm matches CloudRepo’s, and `publishTo` if you publish.

## Before you start

- A Maven repository to read from and publish to. [Creating a Repository](/docs/manage/repositories.html#creating-a-repository) explains how to make one.
- A repository token that covers it. Choose **Download and publish packages** when you publish. [Repository Tokens](/docs/authenticate/repository-tokens.html) shows how to create one. In sbt’s terms, `user` is the email address that owns the token and `password` is the token.
- The repository address, `https://your-org.mycloudrepo.io/repositories/your-repo`. Its [Connection Settings](/docs/manage/repositories.html#view-connection-settings) page displays the same address with your organization and repository already filled in.
- sbt 1.x. The output quoted on this page comes from sbt 1.13.0.

> **Note:** The credential sbt sends is a repository token. The password you sign in to the admin portal with is not that credential.

## Connect sbt

**sbt**

**1. Put the credential in `~/.sbt/.credentials`.** The file is Java properties. `realm` and `host` are both your repository host, and `user` and `password` are your email address and the token. Keep the file readable by you alone (`chmod 600 ~/.sbt/.credentials`).

`~/.sbt/.credentials`

```ini
realm=your-org.mycloudrepo.io
host=your-org.mycloudrepo.io
user=you@example.com
password=YOUR_REPOSITORY_TOKEN
```

**2. Name the repository in `build.sbt`.** `resolvers` is where sbt reads dependencies from, `credentials` loads the file you wrote, and `publishTo` is where `sbt publish` writes:

`build.sbt`

```scala
resolvers += "CloudRepo" at "https://your-org.mycloudrepo.io/repositories/your-repo"


credentials += Credentials(Path.userHome / ".sbt" / ".credentials")


publishTo := Some("CloudRepo" at "https://your-org.mycloudrepo.io/repositories/your-repo")
```

**3. Publish.** Run this in the directory of your `build.sbt`:

**Terminal**

```bash
sbt publish
```

Expected: `[success]`, and the artifact is listed in the repository in the [admin portal](https://admin.cloudrepo.io). sbt publishes the pom and the jar, and the sources and javadoc jars. A project that depends on the published coordinate resolves it from the same `resolvers` line, so there is nothing more to run for that.

> **The realm has to match:** sbt sends the credential only when `realm` matches what CloudRepo asks for, which is your repository host. Any other value sends nothing, and the build fails with `unauthorized` (resolving) or `Unable to find credentials` (publishing). Use the same value for `realm` and `host`.

## In CI

Keep the token in the platform’s secret store, expose it to the build step as the environment variable `CLOUDREPO_TOKEN` (and your email as `CLOUDREPO_USERNAME`), and read both in `build.sbt` instead of a file. Nothing goes on a command line:

`build.sbt`

```scala
credentials += Credentials(
  "your-org.mycloudrepo.io",
  "your-org.mycloudrepo.io",
  sys.env("CLOUDREPO_USERNAME"),
  sys.env("CLOUDREPO_TOKEN")
)
```

For how each CI system holds a secret, see [CI/CD](/docs/ci/overview.html).

## Send the token on the first request

Your sbt builds can be faster. sbt downloads through Coursier, and by default Coursier sends the token only after CloudRepo has asked for it twice, so every file takes three requests. Add these lines to `build.sbt` and sbt sends the token with the first request: one request per file.

`build.sbt`

```scala
val cloudrepoAuth = for {
  user <- sys.env.get("CLOUDREPO_USERNAME")
  token <- sys.env.get("CLOUDREPO_TOKEN")
} yield "CloudRepo" -> lmcoursier.definitions.Authentication(user, token)
csrConfiguration ~= (c => cloudrepoAuth.fold(c)(a => c.withAuthenticationByRepositoryId(Vector(a))))
updateClassifiers / csrConfiguration ~= (c => cloudrepoAuth.fold(c)(a => c.withAuthenticationByRepositoryId(Vector(a))))
```

- These lines are safe to commit. On a machine where `CLOUDREPO_USERNAME` and `CLOUDREPO_TOKEN` are not both set, they do nothing, and sbt keeps using `~/.sbt/.credentials`.
- `"CloudRepo"` is the name in your `resolvers` line. If you named it something else, use that name.
- Your email and the token come from `CLOUDREPO_USERNAME` and `CLOUDREPO_TOKEN`, set as shown in the [In CI](#in-ci) section.
- The last line does the same for `sbt updateClassifiers`, which downloads sources and javadoc. sbt sets that task up on its own, so the `csrConfiguration` line above it does not reach it.
- Keep the `credentials` line. `sbt publish` reads it.

## Overwrite Protection and the 409

A Maven repository guards its releases unless you turn [Overwrite Protection](/docs/manage/repositories.html#overwrite-protection) off. A second publish of a release version answers `409 Conflict`, and the copy already stored stays untouched. Versions ending in `-SNAPSHOT` are exempt and can be published as often as you like. The rules match Maven’s, described in [Maven Overwrite Protection](/docs/formats/maven.html#maven-overwrite-protection).

Nothing is broken. Raise the version, or switch to a `-SNAPSHOT` version while you are still iterating.

## Troubleshooting

**`unauthorized: https://your-org.mycloudrepo.io/... (your-org.mycloudrepo.io)` while resolving.** sbt asked CloudRepo for the file and sent no credential. The text in parentheses is the realm CloudRepo asked for: put exactly that in `realm` (and in `host`) in `~/.sbt/.credentials`. If the realm already matches, check that `credentials += ...` is in the `build.sbt` of the project that is failing.

**`Unable to find credentials for [your-org.mycloudrepo.io @ your-org.mycloudrepo.io]` while publishing.** Same problem on the publish side. sbt lists the realms it has for that host under `Is one of these realms misspelled for host`, then sends the upload with no credential. Set `realm` to the value in the first brackets.

**`403 Forbidden` after sbt sends the credential.** The credential is good but may not do this. The token does not reach this repository (`scope_mismatch_repo`), or it has **Download packages** access and you are publishing. See [`scope_mismatch_repo`](/docs/reference/error-codes.html#scope_mismatch_repo) and [Troubleshooting](/docs/reference/troubleshooting.html).

**`401 Unauthorized` that a matching realm does not fix.** Either `user` is not the email address that owns the token, or the token has expired or been revoked. Run the checks in [Troubleshooting](/docs/reference/troubleshooting.html#test-the-credential-on-its-own).

---

The page: https://www.cloudrepo.io/docs/formats/sbt.html
