In GitHub Packages, how does Maven find the token for maven.pkg.github.com, and why must the repository id match a settings.xml server id?
answer
- credentials are looked up by name
- the URL names a repository
- lowercase owner, lowercase artifactId
- setup-java writes the server for you
basics
~10 sMaven sends credentials only for a repository whose id matches a server id in ~/.m2/settings.xml; that server holds the GitHub username and a classic token, and the repository URL is https://maven.pkg.github.com/OWNER/REPOSITORY.
solid answer
~40 sMaven never matches credentials by URL. It takes the `<id>` of the repository it is talking to, from `distributionManagement` in the POM for `mvn deploy` or from a `repositories` entry for installs, and looks for a `<server>` with the same `<id>` in `~/.m2/settings.xml`; that server carries your GitHub username and a **personal access token (classic)** with `write:packages` or `read:packages`. If the ids differ, Maven sends the request with no credentials and GitHub Packages refuses it. The URL is `https://maven.pkg.github.com/OWNER/REPOSITORY`, with the owner in lowercase, because Maven packages on GitHub Packages are **repository-scoped**. In GitHub Actions, `actions/setup-java` generates a `settings.xml` whose server id is `github`, using `GITHUB_ACTOR` and `GITHUB_TOKEN`, so the POM's repository id must also be `github`.
code
xml · 9 lines<settings>
<servers>
<server>
<id>github</id>
<username>alice</username>
<password>ghp_xxxxxxxx</password>
</server>
</servers>
</settings>go deeper
Recall that the Maven endpoint includes owner and repository, and that settings.xml holds a username and a classic token in a server entry.
Explain the id join between POM repositories and settings.xml servers, and the server id setup-java generates in a workflow.
Trace a deploy that works locally and fails in CI to the id, the job's packages permission or the naming rules, and keep tokens out of committed POMs.
Decide how many repositories an organisation's Maven artifacts should live in, given that consumers address each one and its permissions come from the repository.
## How the Maven registry in GitHub Packages is addressed **GitHub Packages** hosts Apache Maven (and Gradle) packages at `https://maven.pkg.github.com/OWNER/REPOSITORY`. The repository is part of the address because the Maven and Gradle registries support only **repository-scoped permissions**: a Maven package is published into a repository and follows that repository's permissions. Two naming rules come with the endpoint: - the **owner** in the URL must be lowercase, even if the GitHub account name contains capitals; - the **artifactId** may contain only lowercase letters, digits and hyphens; an uppercase artifact name is rejected with *422 Unprocessable Entity*. To install from any repository of one owner, a consuming project can use `https://maven.pkg.github.com/OWNER/*` as its repository URL. Publishing always targets one named repository. ## How Maven picks a credential Maven keeps credentials apart from build files. The POM, which is committed, names repositories; `~/.m2/settings.xml`, which is per-user, holds secrets in `<server>` entries. The two are joined by **id**, never by host name: 1. `mvn deploy` reads the target repository from `<distributionManagement>` in the POM, including its `<id>`; 2. Maven looks in `settings.xml` for a `<server>` whose `<id>` is the same string; 3. if it finds one, it sends that `<username>` and `<password>`; if it does not, it sends the request **without credentials**, and GitHub Packages refuses it. Installs work the same way: the `<repository>` that points at `maven.pkg.github.com`, whether in the POM or in an active profile in `settings.xml`, needs an id that matches a server. ```xml <distributionManagement> <repository> <id>github</id> <name>GitHub acme Apache Maven Packages</name> <url>https://maven.pkg.github.com/acme/billing</url> </repository> </distributionManagement> ``` ## Which token the server entry holds | Task | Classic token scope | Account role needed | |---|---|---| | install a dependency | `read:packages` | read on the repository | | `mvn deploy` | `write:packages` | write on the repository | Outside a workflow, the only personal token GitHub Packages supports here, as everywhere in the product, is a **personal access token (classic)**, and a token is needed to install even a public Maven package. `SNAPSHOT` versions are supported; to download them, a consuming build enables snapshots on that repository in the POM or in `settings.xml`. ## In a GitHub Actions workflow In a workflow there is no `settings.xml` to edit by hand. `actions/setup-java` installs the JDK and writes a `settings.xml` for GitHub Packages whose server id is **`github`**, with the `GITHUB_ACTOR` environment variable as username and the `GITHUB_TOKEN` environment variable as password. The workflow then: - gives the job `contents: read` and `packages: write`; - sets the step's `GITHUB_TOKEN` environment variable to the job's `GITHUB_TOKEN` secret; - runs `mvn --batch-mode deploy`. For that to work the POM's `distributionManagement` repository must use the id `github`. A project whose POM says `<id>gh-packages</id>` builds locally, where the developer's own `settings.xml` happens to match, and fails in CI, where the generated server is called `github`. ## Consuming from a laptop A developer who only installs the artifact needs two pieces, again joined by id: 1. a `<server>` in `~/.m2/settings.xml` with the GitHub username and a classic token carrying `read:packages`; 2. a `<repository>` with the same `<id>` and the URL `https://maven.pkg.github.com/acme/billing`, either in the consuming POM or in a profile listed under `<activeProfiles>` in `settings.xml`; 3. `<snapshots><enabled>true</enabled></snapshots>` on that repository if the build depends on a `SNAPSHOT` version. GitHub's own example keeps the public central repository first in the profile and adds the GitHub repository after it, so ordinary dependencies still resolve from where they always did. Gradle builds use the same `maven.pkg.github.com/OWNER/REPOSITORY` endpoint with credentials declared in the build, and the same token rules apply. ## Failure signatures | Symptom | Likely cause | |---|---| | deploy refused although settings.xml holds a valid token | repository id and server id differ, so no credential was sent | | deploy rejected with 422 | uppercase letters in the artifactId | | a dependency is not found though the token is fine | wrong owner or repository in the URL, or the owner written with capitals | | works on a laptop, fails in Actions | POM id is not `github`, or the job lacks `packages: write` | Publishing the same artifact to Maven Central as well is a separate process with its own requirements, covered in the material on Central publishing.
- In GitHub Packages, a Maven build passes locally but mvn deploy fails in GitHub Actions after switching to actions/setup-java. What do you look at?The repository id in the POM's `distributionManagement`. `setup-java` generates a `settings.xml` whose server id is `github`, reading `GITHUB_ACTOR` and `GITHUB_TOKEN`; if the POM uses any other id, Maven finds no matching server and sends no credentials. Also confirm the job grants `packages: write` and that the step sets the `GITHUB_TOKEN` environment variable.
- Why does the Maven endpoint in GitHub Packages include a repository name when the npm endpoint does not?Because the Maven and Gradle registries support only repository-scoped permissions: each package is published into a repository and inherits that repository's permissions. npm packages are scoped to a user or organisation and can have granular permissions, so the npm endpoint is a single host routed by scope.
- Maven matches settings.xml credentials to a repository by its URL host.
- A fine-grained token restricted to one repository works for maven.pkg.github.com.
- The Maven endpoint is just maven.pkg.github.com/OWNER, like an npm scope.
- Mixed-case artifactIds are fine because Maven coordinates are case-insensitive.
- Public Maven packages on GitHub Packages install without any token.