Skip to content
This repository has been archived by the owner on Jan 23, 2023. It is now read-only.

Commit

Permalink
Add guide for deployment setup
Browse files Browse the repository at this point in the history
  • Loading branch information
@samuelmeuli
samuelmeuli committed Dec 2, 2019
1 parent a2dddc6 commit 801e85f
Show file tree
Hide file tree
Showing 2 changed files with 170 additions and 55 deletions.
83 changes: 28 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,55 +2,27 @@

**GitHub Action for automatically publishing Maven packages**

It's recommended to publish using the [Nexus Staging Maven Plugin](https://github.com/sonatype/nexus-maven-plugins/tree/master/staging/maven-plugin), which greatly simplifies the process.
## Overview

## Requirements
This action…

The following instructions assume that you've already configured your repository for deployment using the Nexus Staging Maven Plugin. If you haven't, you can read about how to do this [here](https://central.sonatype.org/pages/apache-maven.html).
- Executes the Maven `deploy` lifecycle phase
- Provides Maven with your GPG key and passphrase so your artifacts can be signed using `maven-gpg-plugin`
- Provides Maven with your Nexus credentials so it can deploy and release your project

In the plugin's configuration, you will probably want to set the following option to automatically deploy to the Central Repository after successfully staging on Nexus:
It will also use the `deploy` Maven profile if you've defined one (in case you want to perform certain steps only when deploying).

```xml
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<!-- ... -->
<configuration>
<!-- ... -->
<autoReleaseAfterClose>true</autoReleaseAfterClose>
</configuration>
</plugin>
```
## Setup

Furthermore, make sure your GPG plugin is configured like this:

```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.6</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
<configuration>
<!-- Prevent `gpg` from using pinentry programs -->
<gpgArguments>
<arg>--pinentry-mode</arg>
<arg>loopback</arg>
</gpgArguments>
</configuration>
</execution>
</executions>
</plugin>
```
### Deployment

It's recommended to publish using the Nexus Staging Maven Plugin, which greatly simplifies the process. You can follow [this guide](./docs/deployment-setup.md) for a simple configuration.

## Usage
Make sure your project is correctly configured for deployment before continuing with the next step.

### Authentication
### Workflow

#### Secrets

In your project's GitHub repository, go to Settings → Secrets. On this page, set the following variables:

Expand All @@ -61,9 +33,7 @@ In your project's GitHub repository, go to Settings → Secrets. On this page, s
- `nexus_username`: Username (not email!) for your Nexus repository manager account
- `nexus_password`: Password for your Nexus account

These secrets will be provided to the action as environment variables, allowing it to perform the deployment for you.

### Action
#### Workflow file

Create a GitHub workflow file (e.g. `.github/workflows/release.yml`) in your repository. Use the following configuration, which tells GitHub to use the Maven Publish Action when running your CI pipeline. The steps are self-explanatory:

Expand Down Expand Up @@ -97,24 +67,27 @@ jobs:
nexus_password: ${{ secrets.nexus_password }}
```
Every time you push to `master`, the action will be executed. If your `pom.xml` file contains a non-snapshot version tag and all tests pass, your package will automatically be deployed.
Every time you push to `master`, the action will be executed. If your `pom.xml` file contains a non-snapshot version number and all tests pass, your package will be deployed automatically.

## Configuration

In addition to the input variables listed above, the action can be configured with the following variables:
In addition to the input variables listed above, the action can be configured with the following options:

- **`server_id`:** The default Nexus instance used by this action is OSSRH. If you are deploying to a different Nexus instance, you can pass in the server ID you've used in your project's POM file (in the `nexus-staging-maven-plugin` and `distributionManagement` configurations)
- **`maven_args`:** Additional flags/arguments to pass to the Maven deploy command
- **`server_id`:** The default Nexus instance used by this action is OSSRH. If you are deploying to a different Nexus instance, you can specify the server ID you've used in your project's POM file (in the `nexus-staging-maven-plugin` and `distributionManagement` configurations) here
- **`maven_args`:** Additional flags/arguments to pass to the Maven `deploy` command

## Development

### Implementation
### Contributing

The Maven Publish GitHub Action works the following way:
Suggestions and contributions are always welcome! Please discuss larger changes via issue before submitting a pull request.

- When imported from a CI workflow in your project, GitHub will look for this repository's [`action.yml`](./action.yml) file. This file tells GitHub to run the `index.js` script and to pass in the action's input variables (e.g. GPG key and Nexus login credentials).
- The script imports the GPG key and runs the Maven deploy command. Maven will use this repository's [`settings.xml`](./settings.xml) file, which instructs it to use the GPG passphrase and Nexus credentials from the provided input variables. Maven will also use the `deploy` profile if you've defined one (in case you want to perform certain steps only when deploying).
### Setup

### Contributing
Make sure you have Node.js and Yarn installed.

Suggestions and contributions are always welcome! Please discuss larger changes via issue before submitting a pull request.
After cloning this repository, do the following:

1. Install all dependencies using `yarn install`. This will set up Git hooks so your code is linted and formatted before creating a commit
2. Make your modifications to the action
3. Test your action on a repository. You can import it from your fork like this: `uses: your-github-username/action-maven-publish@your-branch-name`
142 changes: 142 additions & 0 deletions docs/deployment-setup.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Deployment Setup

**Releasing your Maven project on the Central Repository can be somewhat complicated. One simple way to perform the deployment is using Sonatype's OSS Repository Hosting (OSSRH) platform and the corresponding Maven plugin.**

You can deploy your project on this Nexus instance, which will run a series of checks on your artifacts. If these checks pass, Nexus can automatically publish your project on the Central Repository.

The Maven Deploy Plugin is _not_ required with this setup.

## Requesting a Repository

_This guide assumes that you want to publish an open-source project to the Central Repository and that you'll be using Sonatype OSSRH for staging. If you want to publish to your own Nexus instance instead, this step will be different for you._

To be able to deploy to the Central Repository using Sonatype, you will need an account first. You can create one [here](https://issues.sonatype.org/secure/Signup!default.jspa).

Next, you will need to request a repository for your project on OSSRH. You can do this [here](https://issues.sonatype.org/secure/CreateIssue.jspa?issuetype=21&pid=10134). After providing the required information and opening the ticket, you'll need to wait for one of the maintainers to verify and approve your request. This might take a day or two.

During the wait, you can continue following the steps below to make your project ready for deployment.

## GPG Key

To sign your releases on the Central Repository, you'll need a GPG key. Creating one is easy:

```sh
# On macOS, you will need to install `gnupg` first
brew install gnupg

# Generate a new GPG key
gpg --gen-key
```

Answer the prompts and set a passphrase. Next, run the following command to list your keys:

```sh
gpg --list-keys
```

Find your new key in the list and copy its ID. Send your public key to a key server:

```sh
gpg --keyserver hkps://keys.openpgp.org --send-keys KEY_ID
```

## Project Configuration

To configure your Maven project for deployment to OSSRH, add the following sections to your `pom.xml` file. You'll add a `deploy` profile, which is executed in the `deploy` lifecycle phase. It includes the `maven-source-plugin` for generating source JAR files, the `maven-javadoc-plugin` for including the Javadocs and the `maven-gpg-plugin` for signing your artifacts. You'll also configure the remote repository (`ossrh`):

```xml
<project>
<profiles>
<!-- Deployment profile (required so these plugins are only used when deploying) -->
<profile>
<id>deploy</id>
<build>
<plugins>
<!-- Source plugin -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>2.4</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>

<!-- Javadoc plugin -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.4</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>

<!-- GPG plugin -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.6</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
<configuration>
<!-- Prevent `gpg` from using pinentry programs -->
<gpgArguments>
<arg>--pinentry-mode</arg>
<arg>loopback</arg>
</gpgArguments>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>

<build>
<plugins>
<!-- Nexus Staging Plugin -->
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<version>1.6.8</version>
<extensions>true</extensions>
<configuration>
<serverId>ossrh</serverId>
<nexusUrl>https://oss.sonatype.org/</nexusUrl>
<autoReleaseAfterClose>false</autoReleaseAfterClose>
</configuration>
</plugin>
</plugins>
</build>

<distributionManagement>
<!-- Central Repository -->
<snapshotRepository>
<id>ossrh</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
</distributionManagement>
</project>
```

## Sources

- Sonatype docs ([1](https://central.sonatype.org/pages/apache-maven.html), [2](https://central.sonatype.org/pages/ossrh-guide.html), [3](https://central.sonatype.org/pages/working-with-pgp-signatures.html))
- [Publishing Artifact to Maven Central](https://itnext.io/publishing-artifact-to-maven-central-b160634e5268)

0 comments on commit 801e85f

Please sign in to comment.