Maven

Buildkite Package Registries provides registry support for Maven-based Java packages.

Once your Java source registry has been created, you can publish/upload packages (generated from your application's build) to this registry by configuring your ~/.m2/settings.xml and application's relevant pom.xml files with the Maven XML snippets presented on your Java registry's details page.

To view and copy the required ~/.m2/settings.xml and pom.xml configurations:

Select Package Registries in the global navigation to access the Registries page.
Select your Java source registry on this page.
Select Publish a Java Package and in the resulting dialog's Using Maven section, select Maven to expand this section.
Use the copy icon at the top-right of each respective code box to copy the relevant XML snippet and paste it into its appropriate file.

These file configurations contain the following:

~/.m2/settings.xml: the ID for your specific Java source registry in Buildkite and the API access token required to publish the package to this registry.
pom.xml: the ID and URL for your specific Java source registry in Buildkite.

Publish a package

The following steps describe the process above:

Copy the following XML snippet, paste it into your ~/.m2/settings.xml file, and modify accordingly:
```
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
    http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>org-slug-registry-slug</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer registry-write-token</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>
```
where:
- org-slug-registry-slug is the ID of your Java registry, based on the org and this registry's slugs separated by a hyphen. The org slug can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite. The registry slug is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your Java registry from the Registries page. The Java registry ID can actually be any valid unique value, as long as the same value is used in both your settings.xml and pom.xml files.
- registry-write-token is your API access token used to publish/upload packages to your Java source registry. Ensure this access token has the Read Packages and Write Packages REST API scopes, which allows this token to publish packages to any source registry your user account has access to within your Buildkite organization.
Note: This step only needs to be performed once for the life of your Java source registry, and API access token.
Copy the following XML snippet, paste it into your pom.xml configuration file, and modify accordingly:
```
<distributionManagement>
  <repository>
    <id>org-slug-registry-slug</id>
    <url>https://packages.buildkite.com/{org.slug}/{registry.slug}/maven2/</url>
  </repository>
  <snapshotRepository>
    <id>org-slug-registry-slug</id>
    <url>https://packages.buildkite.com/{org.slug}/{registry.slug}/maven2/</url>
  </snapshotRepository>
</distributionManagement>
```
where:
- org-slug-registry-slug is the ID of your Java source registry (above).
- {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.
- {registry.slug} is the slug of your Java source registry, which is the kebab-case version of this registry's name, and can be obtained after accessing Package Registries in the global navigation > your Java source registry from the Registries page.
Publish your package:
```
mvn deploy
```

Access a package's details

A Java package's details can be accessed from its source registry through the Releases (tab) section of your Java source registry page. To do this:

Select Package Registries in the global navigation to access the Registries page.
Select your Java source registry on this page.
On your Java source registry page, select the package to display its details page.

If your Java source registry is an upstream of a composite registry, you can also access the Java package's details from this composite registry (listed on the Registries page) by selecting the relevant Java composite registry > from the Upstreams tab, select the relevant Java source registry, then its relevant package.

The package's details page provides the following information in the following sections:

Installation (tab): the installation instructions.
Contents (tab, where available): a list of directories and files contained within the package.
Details (tab): a list of checksum values for this package—MD5, SHA1, SHA256, and SHA512.
About this version: a brief (metadata) description about the package.
Details: details about:
- the name of the package (typically the file name excluding any version details and extension).
- the package version.
- the source registry the package is located in.
- the package's visibility (based on its registry's visibility)—whether the package is Private and requires authentication to access, or is publicly accessible.
- the distribution name / version.
- additional optional metadata contained within the package, such as a homepage, licenses, etc.
Pushed: the date when the last package was uploaded to the source registry.
Total files: the total number of files (and directories) within the package.
Dependencies: the number of dependency packages required by this package.
Package size: the storage size (in bytes) of this package.
Downloads: the number of times this package has been downloaded.

Downloading a package

A Java package can be downloaded from the package's details page. To do this:

Access the package's details.
Select Download.

Installing a package from a source registry

A Java package can be installed using code snippet details provided on the package's details page. To do this:

Access the package's details.
Ensure the Installation tab is displayed and select the Maven section to expand it.
Copy each code snippet, and paste them into their respective ~/.m2/settings.xml and pom.xml files (under the project XML tag), modifying the required values accordingly.

Note: The ~/.m2/settings.xml configuration:
- Is not required if your registry is publicly accessible.
- Only needs to be performed once for the life of your Java registry.
You can then run mvn install on this modified pom.xml to install this package.

The ~/.m2/settings.xml code snippet is based on this format:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
    http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>org-slug-registry-slug</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer registry-read-token</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

where:

org-slug-registry-slug is the ID of your Java registry, based on the org and this registry's slugs separated by a hyphen. The org slug can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite. The registry slug is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your Java registry from the Registries page. The Java registry ID can actually be any valid unique value, as long as the same value is used in both your settings.xml and pom.xml files.

registry-read-token is your API access token or registry token used to download packages from your Java source registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.

The pom.xml code snippet is based on this format:

<repositories>
  <repository>
    <id>org-slug-registry-slug</id>
    <url>https://packages.buildkite.com/{org.slug}/{registry.slug}/maven2/</url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.name.domain.my</groupId>
    <artifactId>my-java-package-name</artifactId>
    <version>my-java-package-version</version>
  </dependency>
</dependencies>

where:

org-slug-registry-slug is the ID of your Java registry, based on the org and this registry's slugs separated by a hyphen. The org slug can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite. The registry slug is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your Java registry from the Registries page. The Java registry ID can actually be any valid unique value, as long as the same value is used in both your settings.xml and pom.xml files.

{org.slug} is the org slug, which can be obtained as described above.

{registry.slug} is the slug of your registry, which is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your registry from the Registries page.

com.name.domain.my is the domain name of your Java package (in typical right-to-left order).
my-java-package-name is the name of your Java package.
my-java-package-version is the version number of your Java package.

Installing a package from a composite registry

If your Java source registry is an upstream of a composite registry, you can install one of its packages using the code snippet details provided on the composite registry's Setup & Usage page. To do this:

Select Package Registries in the global navigation to access the Registries page.
Select your Java composite registry on this page.
Select the Setup & Usage tab to display the Usage Instructions page.
Select the Maven tab.
Copy each code snippet, and paste them into their respective ~/.m2/settings.xml and pom.xml files, modifying their values as required. Learn more about this is Configuring the settings.xml and Configuring the pom.xml, below.

To install packages from any of this composite registry's configured upstreams, define each of these packages in their own <dependency/> subsection within <dependencies/> of your pom.xml file, as you would when installing packages from a source registry, and run mvn install on this modified pom.xml.

Configuring the settings.xml

The ~/.m2/settings.xml code snippet is based on this format:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" ... >
  ...
  <servers>
    <server>
      <id>org-slug-registry-slug</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer registry-read-token</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

where:

org-slug-registry-slug is the ID of your Java registry, based on the org and this registry's slugs separated by a hyphen. The org slug can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite. The registry slug is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your Java registry from the Registries page. The Java registry ID can actually be any valid unique value, as long as the same value is used in both your settings.xml and pom.xml files.

registry-read-token is your API access token or registry token used to download packages from your Java composite registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.

To avoid having to store the actual token value in this file (and mitigate its exposure to continuous integration environments), you can reference it using an environment variable. For example, if you set this token value in the environment variable REGISTRY_READ_TOKEN, like:
```
export REGISTRY_READ_TOKEN="YOUR-ACTUAL-TOKEN-VALUE"
```
you can reference this in the <value/> element above as:
```
<value>Bearer ${env.REGISTRY_READ_TOKEN}</value>
```

If you have added the official public registry to this Java composite registry, add the following <mirrors/> element to you settings.xml file too:

  ...
  <mirrors>
    <mirror>
      <id>org-slug-registry-slug</id>
      <name>The name of your Java composite registry</name>
      <url>https://packages.buildkite.com/{org.slug}/{registry.slug}/maven2/</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
  ...

Configuring the pom.xml

The pom.xml code snippet is based on this format:

<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
  ...
  <repositories>
    <repository>
      <id>org-slug-registry-slug</id>
      <name>The name of your Java composite registry</name>
      <url>https://packages.buildkite.com/{org.slug}/{registry.slug}/maven2/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>
</project>

where:

org-slug-registry-slug is the ID of your Java registry, based on the org and this registry's slugs separated by a hyphen. The org slug can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite. The registry slug is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your Java registry from the Registries page. The Java registry ID can actually be any valid unique value, as long as the same value is used in both your settings.xml and pom.xml files.

{org.slug} is the org slug, which can be obtained as described above.

{registry.slug} is the slug of your registry, which is the kebab-case version of your registry name, and can be obtained after accessing Package Registries in the global navigation > your registry from the Registries page.