|
| 1 | +# JReleaser Release Setup |
| 2 | + |
| 3 | +This document describes how to configure and use the JReleaser automation for this project. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +Before triggering a release, ensure you have configured the following GitHub secrets: |
| 8 | + |
| 9 | +### Required Secrets |
| 10 | + |
| 11 | +1. **MAVEN_USERNAME**: Your Sonatype OSSRH username |
| 12 | + - Get this from https://s01.oss.sonatype.org/ |
| 13 | + |
| 14 | +2. **MAVEN_PASSWORD**: Your Sonatype OSSRH password |
| 15 | + - This is your Sonatype OSSRH user token (preferred) or password |
| 16 | + |
| 17 | +3. **GPG_PRIVATE_KEY**: Your GPG private key (base64 encoded) |
| 18 | + - Export your key: `gpg --export-secret-keys YOUR_KEY_ID | base64` |
| 19 | + - Or use: `gpg --export-secret-keys --armor YOUR_KEY_ID | base64` |
| 20 | + |
| 21 | +4. **GPG_PASSPHRASE**: The passphrase for your GPG key |
| 22 | + - This is the password you use to unlock your GPG key |
| 23 | + |
| 24 | +5. **GPG_PUBLIC_KEY**: Your GPG public key |
| 25 | + - Export: `gpg --export --armor YOUR_KEY_ID` |
| 26 | + |
| 27 | +### Setting Up Secrets |
| 28 | + |
| 29 | +1. Go to your repository on GitHub |
| 30 | +2. Navigate to Settings → Secrets and variables → Actions |
| 31 | +3. Click "New repository secret" |
| 32 | +4. Add each of the secrets listed above |
| 33 | + |
| 34 | +## Generating GPG Keys (if you don't have one) |
| 35 | + |
| 36 | +```bash |
| 37 | +# Generate a new GPG key |
| 38 | +gpg --full-generate-key |
| 39 | + |
| 40 | +# List your keys to get the KEY_ID |
| 41 | +gpg --list-secret-keys --keyid-format=long |
| 42 | + |
| 43 | +# Export the public key for upload to key servers |
| 44 | +gpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEY_ID |
| 45 | + |
| 46 | +# Export for GitHub secret (base64 encoded) |
| 47 | +gpg --export-secret-keys --armor YOUR_KEY_ID | base64 -w 0 |
| 48 | +``` |
| 49 | + |
| 50 | +## Triggering a Release |
| 51 | + |
| 52 | +1. Go to the **Actions** tab in your GitHub repository |
| 53 | +2. Select the **Release** workflow from the left sidebar |
| 54 | +3. Click **Run workflow** (on the right side) |
| 55 | +4. Enter the release version (e.g., `1.0.0`, `1.1.0`, etc.) |
| 56 | +5. Click **Run workflow** |
| 57 | + |
| 58 | +## What Happens During Release |
| 59 | + |
| 60 | +The workflow will: |
| 61 | + |
| 62 | +1. **Set Version**: Update all POM files to the release version |
| 63 | +2. **Build**: Compile and verify the project |
| 64 | +3. **Sign**: Sign all artifacts with GPG |
| 65 | +4. **Stage**: Deploy artifacts to the local staging directory |
| 66 | +5. **Release to Maven Central**: Deploy only the `netty-virtualthread-core` artifact to Maven Central |
| 67 | +6. **Create GitHub Release**: Create a GitHub release with changelog |
| 68 | +7. **Bump Version**: Automatically increment the version and add `-SNAPSHOT` suffix |
| 69 | +8. **Commit & Push**: Push the new SNAPSHOT version back to the master branch |
| 70 | + |
| 71 | +## Release Artifacts |
| 72 | + |
| 73 | +- **Published to Maven Central**: `netty-virtualthread-core` only |
| 74 | +- **Not Published**: `benchmarks`, `example-echo` (versions are still bumped to SNAPSHOT) |
| 75 | + |
| 76 | +## Configuration Files |
| 77 | + |
| 78 | +- `.github/workflows/release.yml`: GitHub Actions workflow |
| 79 | +- `.mvn/jreleaser.yml`: JReleaser configuration |
| 80 | +- `pom.xml`: Maven configuration with release profile |
| 81 | + |
| 82 | +## Troubleshooting |
| 83 | + |
| 84 | +### Release fails at Maven Central stage |
| 85 | + |
| 86 | +- Check that MAVEN_USERNAME and MAVEN_PASSWORD are correct |
| 87 | +- Ensure you have proper permissions in Sonatype OSSRH |
| 88 | +- Check the staging repository at https://s01.oss.sonatype.org/ |
| 89 | + |
| 90 | +### Release fails at GPG signing |
| 91 | + |
| 92 | +- Verify GPG_PRIVATE_KEY is properly base64 encoded |
| 93 | +- Check that GPG_PASSPHRASE is correct |
| 94 | +- Ensure the GPG key is not expired |
| 95 | + |
| 96 | +### GitHub release creation fails |
| 97 | + |
| 98 | +- The GITHUB_TOKEN is automatically provided by GitHub Actions |
| 99 | +- Check repository permissions in Settings → Actions → General |
| 100 | + |
| 101 | +## Manual Cleanup |
| 102 | + |
| 103 | +If a release fails partway through: |
| 104 | + |
| 105 | +1. Delete the Git tag if created: `git push --delete origin TAG_NAME` |
| 106 | +2. Delete the GitHub release if created (in Releases section) |
| 107 | +3. Drop the staging repository in Sonatype if artifacts were staged |
| 108 | +4. Reset version in POM files: `mvn versions:set -DnewVersion=X.Y.Z-SNAPSHOT` |
| 109 | + |
| 110 | +## Support |
| 111 | + |
| 112 | +For issues with: |
| 113 | +- JReleaser: https://github.com/jreleaser/jreleaser/discussions |
| 114 | +- Maven Central: https://central.sonatype.org/support/ |
| 115 | +- GPG: https://www.gnupg.org/documentation/ |
0 commit comments