Skip to content

Commit de6f65c

Browse files
kwentkwent
committed
Add comprehensive publishing documentation
- Create PUBLISHING.md with step-by-step guide for: - Setting up Sonatype OSSRH account - Generating and configuring GPG keys - Configuring GitHub secrets - Publishing process and troubleshooting - Update CLAUDE.md with publishing overview - Protect PUBLISHING.md from regeneration in .openapi-generator-ignore Publishing is now configured for: - Maven Central (with GPG signing) - GitHub Packages (automatic with GITHUB_TOKEN)
1 parent becc9bf commit de6f65c

File tree

3 files changed

+172
-1
lines changed

3 files changed

+172
-1
lines changed

‎.openapi-generator-ignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,5 @@ pom.xml
2828
LICENSE
2929
README.md
3030
CLAUDE.md
31+
PUBLISHING.md
3132
.github/dependabot.yml

‎CLAUDE.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,17 @@ The project uses **Spotless** with **Google Java Format (AOSP style)**:
157157
GitHub Actions workflows:
158158
- **test.yml** - Runs tests on all branches using JDK 17
159159
- **maven.yml** - Maven-based build pipeline
160-
- **publish.yml** - Publishes artifacts
160+
- **publish.yml** - Publishes artifacts to Maven Central and GitHub Packages (triggered on releases)
161+
162+
## Publishing
163+
164+
See [PUBLISHING.md](PUBLISHING.md) for detailed instructions on publishing releases to Maven Central and GitHub Packages.
165+
166+
Quick overview:
167+
1. Update version: `make bump-patch` (or bump-minor/bump-major)
168+
2. Push tag: `make push-tag`
169+
3. Create GitHub release: `gh release create v0.0.2`
170+
4. Workflow automatically publishes to both registries
161171

162172
## Important Notes
163173

‎PUBLISHING.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Publishing Guide
2+
3+
This document describes how to publish the rootly-java SDK to Maven Central and GitHub Packages.
4+
5+
## Prerequisites
6+
7+
### 1. Sonatype OSSRH Account
8+
9+
Create an account and request access to publish under the `com.rootly.client` groupId:
10+
1. Create a [Sonatype JIRA account](https://issues.sonatype.org/secure/Signup!default.jspa)
11+
2. Create a ticket requesting access to `com.rootly.client` groupId
12+
3. Follow the verification process (may require domain ownership proof)
13+
14+
### 2. GPG Key for Signing
15+
16+
Maven Central requires all artifacts to be signed with GPG:
17+
18+
```bash
19+
# Generate a GPG key
20+
gpg --gen-key
21+
22+
# List your keys
23+
gpg --list-keys
24+
25+
# Export your public key (submit to key server)
26+
gpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEY_ID
27+
28+
# Export your private key (for GitHub Secrets)
29+
gpg --export-secret-keys YOUR_KEY_ID | base64
30+
```
31+
32+
### 3. Configure GitHub Secrets
33+
34+
Add the following secrets to your GitHub repository (Settings → Secrets and variables → Actions):
35+
36+
| Secret Name | Description | How to Get |
37+
|-------------|-------------|------------|
38+
| `MAVEN_USERNAME` | Sonatype OSSRH username | Your JIRA username |
39+
| `MAVEN_PASSWORD` | Sonatype OSSRH password or token | Your JIRA password or [generated token](https://oss.sonatype.org/#profile;User%20Token) |
40+
| `GPG_PRIVATE_KEY` | GPG private key in base64 | Run: `gpg --export-secret-keys YOUR_KEY_ID \| base64` |
41+
| `GPG_PASSPHRASE` | Passphrase for GPG key | The passphrase you set when creating the GPG key |
42+
43+
**Note**: GitHub Packages publishing uses the automatic `GITHUB_TOKEN` and requires no manual setup.
44+
45+
## Publishing Process
46+
47+
The publish workflow runs automatically when you create a GitHub release.
48+
49+
### Step 1: Update Version
50+
51+
Update the version in both build files:
52+
53+
```bash
54+
# Update version in pom.xml
55+
sed -i '' 's/<version>0.0.1<\/version>/<version>0.0.2<\/version>/' pom.xml
56+
57+
# Update version in build.gradle
58+
sed -i '' "s/version = '0.0.1'/version = '0.0.2'/" build.gradle
59+
60+
# Or use the Makefile
61+
make bump-patch # 0.0.1 -> 0.0.2
62+
make bump-minor # 0.0.1 -> 0.1.0
63+
make bump-major # 0.0.1 -> 1.0.0
64+
```
65+
66+
### Step 2: Commit and Push
67+
68+
```bash
69+
git add pom.xml build.gradle
70+
git commit -m "Bump version to 0.0.2"
71+
git push origin master
72+
```
73+
74+
### Step 3: Create a Release
75+
76+
Create a release via GitHub UI or CLI:
77+
78+
```bash
79+
# Using GitHub CLI
80+
gh release create v0.0.2 --title "Release 0.0.2" --notes "Release notes here"
81+
82+
# Or push the tag created by make
83+
make push-tag
84+
```
85+
86+
### Step 4: Monitor the Workflow
87+
88+
The publish workflow will:
89+
1. Run all tests
90+
2. Deploy to Maven Central (with GPG signing)
91+
3. Deploy to GitHub Packages
92+
93+
Check the Actions tab in GitHub for progress.
94+
95+
### Step 5: Release on Maven Central
96+
97+
After the workflow completes:
98+
1. Go to [Sonatype OSSRH](https://oss.sonatype.org/)
99+
2. Log in with your credentials
100+
3. Click "Staging Repositories" in the left sidebar
101+
4. Find your repository (com.rootly.client)
102+
5. Click "Close" to validate the artifacts
103+
6. Once validation passes, click "Release" to publish
104+
105+
Artifacts will be available on Maven Central within 2 hours and synchronized to Maven Central search within 4 hours.
106+
107+
## Verification
108+
109+
### Maven Central
110+
111+
```xml
112+
<dependency>
113+
<groupId>com.rootly.client</groupId>
114+
<artifactId>rootly</artifactId>
115+
<version>0.0.2</version>
116+
</dependency>
117+
```
118+
119+
### GitHub Packages
120+
121+
```xml
122+
<repositories>
123+
<repository>
124+
<id>github</id>
125+
<url>https://maven.pkg.github.com/rootlyhq/rootly-java</url>
126+
</repository>
127+
</repositories>
128+
129+
<dependency>
130+
<groupId>com.rootly.client</groupId>
131+
<artifactId>rootly</artifactId>
132+
<version>0.0.2</version>
133+
</dependency>
134+
```
135+
136+
## Troubleshooting
137+
138+
### GPG Signing Fails
139+
140+
- Verify `GPG_PRIVATE_KEY` is base64 encoded correctly
141+
- Ensure `GPG_PASSPHRASE` matches your key's passphrase
142+
- Check that the key hasn't expired: `gpg --list-keys`
143+
144+
### Maven Central Deployment Fails
145+
146+
- Verify `MAVEN_USERNAME` and `MAVEN_PASSWORD` are correct
147+
- Check that you have permission for the `com.rootly.client` groupId
148+
- Review Sonatype JIRA ticket status
149+
150+
### GitHub Packages Deployment Fails
151+
152+
- Verify the workflow has `packages: write` permission
153+
- Check that `GITHUB_TOKEN` is being passed correctly
154+
- Ensure the repository URL matches your GitHub repository
155+
156+
## Resources
157+
158+
- [Maven Central Guide](https://central.sonatype.org/publish/publish-guide/)
159+
- [GitHub Packages Maven](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)
160+
- [GPG Key Generation](https://central.sonatype.org/publish/requirements/gpg/)

0 commit comments

Comments
 (0)