Developer's Notes

Site Generation

set MACHA_SITE=D:\projects\machanism.org\@macha
mvn clean site site:stage

see: Maven Site Plugin Usage

Central Deployment

When deploying a project to Maven Central, you need to properly configure your Maven settings.xml to handle repository credentials, signing, and deployment details. Below, we’ll explain the key components of your provided configuration and how they facilitate successful deployment.

Maven settings.xml Configuration

The provided settings.xml includes several important configurations, such as repository definitions, GPG signing for artifacts, and authentication credentials. Let’s break it down:

GPG Signing Setup

To deploy on Maven Central, all artifacts must be signed using GNU Privacy Guard (GPG). The settings.xml includes configurations for the maven-gpg-plugin, which ensures that your artifacts are properly signed before deployment.

Key Elements:
<profile>
    <id>release</id>
    <properties>
        <gpg.executable>gpg</gpg.executable>
        <gpg.keyname>YOUR_GPG_KEY_ID</gpg.keyname>
    </properties>
</profile>
  • gpg.executable: Specifies the GPG executable to use for signing. If you’re working in a system where GPG isn't in the default path, ensure this points to the correct location.
  • gpg.keyname: Sets the GPG key ID used for signing artifacts. Replace YOUR_GPG_KEY_ID with the key ID of your GPG key.
Additional Reference:

For detailed usage of the Maven GPG plugin, refer to the Maven GPG Plugin documentation.

Configuring Repositories

The settings.xml includes both release and snapshot repository configurations, ensuring that Maven can route the correct artifacts to the appropriate repositories.

Key Elements:
<repositories>
    <repository>
        <id>central-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots</url>
        <releases><enabled>false</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
    <repository>
        <id>central</id>
        <url>https://repo1.maven.org/maven2/</url>
        <releases><enabled>true</enabled></releases>
        <snapshots><enabled>false</enabled></snapshots>
    </repository>
</repositories>

  • central-snapshots Repository:
    Configures the snapshots repository for publishing or retrieving pre-release versions of your artifacts.

    • url: Snapshot repository URL.
    • Enables snapshot uploads but disables releases.

  • central Repository:
    Configures the main repository (Maven Central) where stable releases are published.

    • url: Central repository URL.
    • Enables releases and disables snapshots.
Related References:

Plugin Repositories

To ensure plugin functionality (like artifact signing, deployment, etc.), the provisioned pluginRepositories section allows access to specific Maven plugin repositories.

Key Elements:
<pluginRepositories>
    <pluginRepository>
        <id>plugin-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots</url>
    </pluginRepository>
</pluginRepositories>
  • Provides specific snapshots of Maven plugins used for build or deployment workflows.

Authentication and Credentials

To securely authenticate and deploy artifacts to Maven Central, add your credentials using the servers section in the settings.xml file.

Key Elements:
<servers>
    <server>
        <id>central</id>
        <username><!-- your token username --></username>
        <password><!-- your token password --></password>
    </server>
</servers>
  • id=central: Matches the repository ID defined in your pom.xml (usually "central" for Maven Central).
  • username and password: Use the Sonatype Account Token (preferred) instead of your regular username/password. Refer to the Sonatype Publishing Guide to generate a deployment token.

Activating the Profile

The configuration defines a release profile but doesn’t explicitly activate it. Ensure that you activate this profile when deploying artifacts:

  • In the Command Line:
    Use the -P flag to activate the release profile: 
    mvn clean deploy -P release

End-to-End Workflow

Here’s the general process to deploy on Maven Central with this settings.xml configuration:

  1. Prepare Artifacts: Ensure your project is ready, and all configurations (e.g., POM metadata, GPG setup) are complete.
  2. Build Project: Use Maven to generate artifacts: 
    mvn clean package
  3. Sign Artifacts: With GPG properly configured, Maven automatically signs the artifacts during deployment.
  4. Deploy Artifacts: Use the deploy goal to publish your artifacts to the appropriate repository: 
    mvn clean deploy -P release

Additional Notes

  • Ensure your Maven version and GPG installation are up-to-date to avoid compatibility issues.
  • Check your Sonatype account settings to ensure authentication is valid.
  • Troubleshoot and validate deployment by checking the artifact in the Sonatype Central Repository portal.

By following these steps and utilizing this configuration, you ensure a seamless Maven Central deployment process that adheres to best practices for secure and efficient artifact management.