Get started with Maven Package Management in VSTS and TFS

VSTS | TFS 2018

Before you start

This guide assumes you've already set up Package Management. You can check out how to install and license the extension in the Install and license Package Management guide, or go directly to the Marketplace listing to install it.

Prerequisites

  1. Apache Maven installed. It can be downloaded from the Apache Maven Site.

  2. Have Package Management installed in your VSTS account.

Create a feed

Already have a feed? Skip to the next step.

A feed is a container for packages. You consume and publish packages through a particular feed.

  1. Navigate to the Packages hub in the Build & Release hub group:

    Go to Packages hub

  2. Click the dropdown in the top left and select New feed:

    New feed button

  3. In the dialog:

    • Give the feed a name.
    • Choose who can read and contribute (or update) packages in your feed.
    • Choose the upstream sources for your feed.
    • When you're done, choose Create.

Most of the default settings work great for most feed users. Making your feed account visible means it's easy to share a single source of packages across your entire team. Enabling upstream sources to public sources makes it easy to use your favorite OSS packages, and can also give you additional protection against outages and corrupted or compromised packages.

New feed dialog

You can change these settings later by editing the feed.

Set up authentication

To talk to VSTS feeds, you'll need a token on your local machine that Maven can pick up and pass to VSTS.

  1. Navigate to the feed that you'd like to use and select Connect to feed.

    Connect to feed button in the upper-right of the page

  2. Open the Maven tab, choose Generate Maven credentials, and copy the generated credentials. (images below)

    • Maven pulls credentials from your settings.xml file.

    • On Linux, the file path is usually "${user.home}/.m2/settings.xml"

    • On macOS, the file path is usually "~/.m2/settings.xml"

    • On Windows, the file path is usually "%USERPROFILE%/.m2/settings.xml"

    • If the file doesn't exist, create one now.

  3. Inside the <settings> and <servers> elements in the file, paste the credentials you copied in Step 3 above.

Sample settings.xml:

<settings>
  <servers>
    <!-- Copy this section from the Maven section of the "Connect to Feed" dialog" -->
    <server>
      <id>yourAccount-visualstudio.com-yourFeedName</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <!--The generated token expires on or before 7/19/2017-->
            <value>Basic Y2Fqb...</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

NOTE: You can find more information about the settings.xml file in the settings.xml reference.

Publish an artifact

Publish Maven artifacts to a feed in Package Management to share them with your team and organization.

To publish a Maven artifact, you'll need to have a Maven artifact to publish on your local machine. If you don't have one, you can generate one by running the following command:

mvn -B archetype:generate -DarchetypeGroupId="org.apache.maven.archetypes" -DgroupId="MyGroup" -DartifactId="myFirstApp"
  1. Set up the Maven client with your feed.

  2. Navigate to the directory containing your Maven artifact's pom.xml file. If you've just created an artifact, the pom.xml file will be in the myFirstApp folder.

  3. From the Connect to feed dialog in VSTS, copy the <repository> information. Paste it into your pom.xml file twice (see the sample file above):

    • Between the <repositories> tags.
    • Between the <distributionManagement> tags.
  4. From the directory containing your pom.xml file, run the command mvn deploy. The Maven artifact should appear in your feed.

Sample pom.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>MyGroup</groupId>
   <artifactId>myFirstApp</artifactId>
   <packaging>jar</packaging>
   <version>1.0-SNAPSHOT</version>
   <name>myFirstApp</name>
   <url>http://maven.apache.org</url>
   <dependencies>
      <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
         <version>3.8.1</version>
         <scope>test</scope>
      </dependency>
   </dependencies>
   <repositories>
    <!-- Copy this section from the Maven section of the "Connect to Feed" dialog -->
      <repository>
         <id>mseng-visualstudio.com-zcalvinmaven</id>
         <url>https://mseng.pkgs.visualstudio.com/_packaging/zCalvinMaven2/maven/v1</url>
         <releases>
            <enabled>true</enabled>
         </releases>
         <snapshots>
            <enabled>true</enabled>
         </snapshots>
      </repository>
   </repositories>
   <distributionManagement>
    <!-- Copy this section from the Maven section of the "Connect to Feed" dialog -->
      <repository>
         <id>mseng-visualstudio.com-zcalvinmaven</id>
         <url>https://mseng.pkgs.visualstudio.com/_packaging/zCalvinMaven2/maven/v1</url>
         <releases>
            <enabled>true</enabled>
         </releases>
         <snapshots>
            <enabled>true</enabled>
         </snapshots>
      </repository>
   </distributionManagement>
</project>

See the Maven CLI docs for more publish options.

Install an artifact from your feed

Install Maven artifacts from your feed using the Maven client.

The most common way to install a Maven artifact is as a dependency of another artifact.

  1. Create a Maven artifact using the following command:
mvn -B archetype:generate -DarchetypeGroupId="org.apache.maven.archetypes" -DgroupId="MyGroup" -DartifactId="mySecondApp"
  1. From the Connect to feed dialog in VSTS, copy the <repository> information. Paste it into your pom.xml file twice (see the sample file above):

    • Between the <repositories> tags.
    • Between the <distributionManagement> tags.
  2. In VSTS Package Management, browse to the artifact you want to install and copy the contents of the <dependency> element.

  3. Paste the <dependency> element content inside the <dependencies> element of your pom.xml file.

  4. Run mvn install from the directory containing your pom.xml file.

See the Maven CLI docs for more install options.

Automate the process with continuous integration

You can use continuous integration systems such as Team Build to automate the installation and publishing of your Maven artifacts. To get started with continuous integration, see the Maven in Team Build guidance.

What's next?

For more advanced topics, check out the content summary.