Maven

Buildkite Packages provides registry support for Maven-based Java packages.

Once your Java 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 Packages in the global navigation to access the Registries page.
Select your Java registry on this page.
Select Publish a Java Package and in the resulting dialog's Using Maven 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 registry in Buildkite and API write token (generated by Buildkite Packages) required to publish the package to this registry
pom.xml: the ID and URL for your specific Java registry in Buildkite.

Publish a package

The following steps describe the process above:

Copy the following XML snippet, paste it into modify 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-name</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer registry-write-token</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>
```
where:
- registry-write-token is the Buildkite Packages-generated API token required to publish/upload packages to your Java registry.
- org-slug-registry-name is the ID of your Java registry, based on the org slug and Java registry names separated by a hyphen. The org slug can be obtained from the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite. 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.
Note: This step only needs to be conducted once for the life of your Java registry.

Copy the following XML snippet, paste it into your pom.xml configuration file, and modify accordingly:

<distributionManagement>
  <repository>
    <id>org-slug-registry-name</id>
    <url>https://buildkitepackages.com/{org.slug}/{registry.name}/maven2/</url>
  </repository>
  <snapshotRepository>
    <id>org-slug-registry-name</id>
    <url>https://buildkitepackages.com/{org.slug}/{registry.name}/maven2/</url>
  </snapshotRepository>
</distributionManagement>

where:

org-slug-registry-name is the ID of your Java registry (above).

{org.slug} can be obtained from the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.

{registry.name} is the name of your Java registry.

Publish your package:
```
mvn deploy
```

Access a package's details

A Java package's details can be accessed from this registry using the Packages section of your Java registry page.

To access your Java package's details page:

Select Packages in the global navigation to access the Registries page.
Select your Java registry on this page.
On your Java registry page, select the package within the Packages section. The package's details page is displayed.

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 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.
Last pushed: the date when the last package was uploaded to the 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 download a package:

Access the package's details.
Select Download.

Installing a package

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

To install a package:

Access the package's details.
Ensure the Installation > Installation instructions section is displayed.
Copy each code snippet, and paste them into their respective ~/.m2/settings.xml and pom.xml files (under the project XML tag), and run mvn install on this modified pom.xml to install this package.

Note: The ~/.m2/settings.xml configuration:
- Is not required if your registry is publicly accessible.
- Only needs to be conducted once for the life of your Java registry.

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-name</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer registry-read-token</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

where:

registry-read-token is the Buildkite Packages-generated API token required to download packages to your Java registry.

org-slug-registry-name is the ID of your Java registry, based on the org slug and Java registry names separated by a hyphen. The org slug can be obtained from the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite. 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.

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

<repositories>
  <repository>
    <id>org-slug-registry-name</id>
    <url>https://buildkitepackages.com/{org.slug}/{registry.name}/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-name is the ID of your Java registry, based on the org slug and Java registry names separated by a hyphen. The org slug can be obtained from the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite. 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.

{registry.name} is the name of your Java registry.

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.