skip to content

What is a Maven wagon, and how do you add support for a repository protocol Maven doesn't ship?

level: seniorimportance: should knowfreq 30%

answer

  1. wagon = transport SPI per protocol
  2. http/file built in; scp/ftp/webdav = extension
  3. wagon-ssh, wagon-ftp, wagon-webdav
  4. credentials via settings.xml <servers> by id
  5. resolver transports vs wagon bridge

basics

~20 s

A wagon is Maven's transport provider for talking to a repository over a given protocol (http, scp, ftp). To use a protocol Maven doesn't ship, you add the matching wagon as a build/core extension so the protocol's URLs resolve.

solid answer

~40 s

Maven abstracts repository transport behind the Wagon API — each protocol (http/https, file, scp, sftp, ftp, webdav) has a Wagon implementation that knows how to get/put artifacts. The HTTP transport is built in, but for ssh/scp, ftp, or webdav you must contribute the provider yourself by declaring the wagon as an extension (e.g. wagon-ssh, wagon-ftp). You put it under <build><extensions> (or .mvn/extensions.xml), and then a <distributionManagement> or repository URL like scp://host/path resolves. Credentials come from settings.xml <servers>. Note that modern Maven (Resolver) also has a newer 'maven-resolver-transport-*' layer (http, file, wagon), but custom/legacy protocols still go through wagon extensions. So: wagon = pluggable transport SPI; add the provider as an extension to teach Maven a new protocol.

code

xml · 9 lines
xml
<build>
  <extensions>
    <extension>
      <groupId>org.apache.maven.wagon</groupId>
      <artifactId>wagon-ssh</artifactId>
      <version>3.5.3</version>
    </extension>
  </extensions>
</build>

go deeper

for a junior

Knows Maven downloads/uploads artifacts over the network.

for a middle

Knows wagons handle protocols and that non-HTTP ones may need adding.

for a senior

Can wire a wagon extension, match it to settings.xml servers, and distinguish wagon from resolver transports.

for a principal

Decides org transport strategy (mirrors, protocols, custom wagons) and credential governance/secret management.

## What a wagon is Maven needs to **fetch** dependencies from and **publish** artifacts to repositories. The mechanism that actually moves bytes over the wire is abstracted by the **Wagon** API (an SPI — service provider interface). Each supported protocol has a wagon implementation: - `file://` — local filesystem (built in) - `http://` / `https://` — built in (now also via maven-resolver-transport-http) - `scp://`, `sftp://`, `ssh` — `wagon-ssh` - `ftp://` — `wagon-ftp` - `dav:`/`webdav` — `wagon-webdav-jackrabbit` ## Why you need to add one Maven ships the common transports, but **scp, ftp, and webdav are not bundled**. If a `<repository>` or `<distributionManagement>` URL uses one of those (or a fully custom protocol), Maven won't know how to talk to it until you supply the wagon as an **extension**. ```xml <build> <extensions> <extension> <groupId>org.apache.maven.wagon</groupId> <artifactId>wagon-ssh</artifactId> <version>3.5.3</version> </extension> </extensions> </build> ``` Then a distribution target like: ```xml <distributionManagement> <repository> <id>internal-ssh</id> <url>scp://repo.example.com/var/www/maven2</url> </repository> </distributionManagement> ``` ## Credentials The wagon authenticates using the matching `<server>` block in `settings.xml`, keyed by the repository `id`: ```xml <servers> <server> <id>internal-ssh</id> <username>deploy</username> <privateKey>${user.home}/.ssh/id_rsa</privateKey> </server> </servers> ``` ## Wagon vs. maven-resolver transports Modern Maven uses **Maven Resolver** (formerly Aether) for dependency resolution; it has its own transport layer (`maven-resolver-transport-http`, `-file`, and a `-wagon` bridge). For everyday HTTP this is what runs. But for protocols outside the resolver transports — scp, ftp, custom — you still register a **wagon extension**, and the resolver's wagon bridge uses it. ## Summary Wagon is the pluggable transport SPI. To teach Maven a new repository protocol, add the protocol's wagon as a build or core extension, then use that scheme in your repository/distribution URLs with credentials from settings.xml.

  • Where do the credentials for an scp wagon deploy come from?
    From a <server> entry in settings.xml whose <id> matches the repository's id; it supplies username/password or privateKey/passphrase.
  • Is HTTP a wagon you must add?
    No — HTTP/HTTPS transport ships with Maven (via the resolver http transport / built-in wagon); only protocols like scp, ftp, webdav need an added wagon extension.

A wagon is a delivery courier that only speaks one shipping protocol; to ship via a new carrier you hire the matching courier (extension).

saying these in an interview costs you the question

  • Saying you must add a wagon for plain HTTP repositories.
  • Putting credentials in the pom.xml instead of settings.xml <servers>.
  • Confusing wagon (transport) with a repository manager like Nexus/Artifactory.

context

resolving links…