Skip to content

Commit c6a7425

Browse files
devalogdevalog
authored
Expand Maven Central publishing page (SDKs) (#801)
1 parent 08eee5e commit c6a7425

File tree

1 file changed

+153
-28
lines changed

1 file changed

+153
-28
lines changed

‎fern/products/sdks/overview/java/publishing-to-maven-central.mdx‎

Lines changed: 153 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,28 @@ Publish your public-facing Fern Java SDK to the [Maven Central
77
registry](https://central.sonatype.com/). After following the steps on this
88
page, you'll have a versioned package published on Maven Central.
99

10-
<Markdown src="/products/sdks/snippets/setup-fern-folder-callout.mdx"/>
10+
<Info>
11+
This page assumes that you have:
1112

12-
## Configure `generators.yml`
13+
* An initialized `fern` folder. See [Set up the `fern`
14+
folder](/sdks/overview/quickstart).
15+
* A GitHub repository for your Java SDK. See [Project structure](/sdks/overview/project-structure).
16+
* A Java generator group in `generators.yml`. See [Java
17+
Quickstart](quickstart#add-the-sdk-generator).
18+
19+
</Info>
20+
21+
## Configure Maven Central publication
22+
23+
You'll need to update your `generators.yml` file to configure the output location, target repository, and publishing mode. Your `generators.yml` [should live in your source repository](/sdks/overview/project-structure) (or on your local machine), not the repository that contains your Java SDK code.
1324

1425
<Steps>
1526

16-
<Step title="Configure `output` location">
27+
<Step title="Configure `output` location">
1728

18-
Change the output location in `generators.yml` from `local-file-system` (the default) to `maven` to indicate that Fern should publish your package directly to the Maven Central registry.
19-
20-
Then, add `publish-to: central` to indicate that the publish target is the new Maven Central Portal (Sonatype). To publish to the legacy Nexus Repository, use `publish-to: ossrh`.
29+
In the `group` for your Java SDK, change the output location in `generators.yml` from `local-file-system` (the default) to `maven` to indicate that Fern should publish your package directly to the Maven Central registry.
30+
31+
Then, add `publish-to: central` to indicate that the publish target is the new Maven Central Portal (Sonatype). To publish to the legacy Nexus Repository, use `publish-to: ossrh`.
2132

2233
```yaml {6-9} title="generators.yml"
2334
groups:
@@ -34,7 +45,7 @@ page, you'll have a versioned package published on Maven Central.
3445
3546
<Step title="Add repository location">
3647
37-
Add the path to your GitHub repository.
48+
Add the path to the GitHub repository containing your Java SDK:
3849
3950
```yaml {10-11} title="generators.yml"
4051
groups:
@@ -51,6 +62,27 @@ groups:
5162
```
5263
5364
</Step>
65+
<Step title="Choose your publishing mode">
66+
67+
<Markdown src="/products/sdks/snippets/github-publishing-mode.mdx"/>
68+
69+
```yaml title="generators.yml" {12-13}
70+
groups:
71+
java-sdk:
72+
generators:
73+
- name: fernapi/fern-java-sdk
74+
version: <Markdown src="/snippets/version-number-java.mdx"/>
75+
output:
76+
location: maven
77+
config:
78+
publish-to: central
79+
github:
80+
repository: your-org/company-java
81+
mode: push
82+
branch: your-branch-name # Required for mode: push
83+
```
84+
85+
</Step>
5486
</Steps>
5587

5688
## Set up Maven Central publishing authentication
@@ -195,37 +227,130 @@ Finally, upload your key to public key servers so Maven Central can access the s
195227
```
196228
</Step>
197229
</Steps>
230+
## Publish your SDK
198231

199-
## Release your SDK to Maven Central
232+
Decide how you want to publish your SDK to Maven Central. You can use GitHub workflows for automated releases or publish directly via the CLI.
200233

201-
At this point, you're ready to generate a release for your SDK.
234+
<AccordionGroup>
235+
236+
<Accordion title="Release via a GitHub workflow">
237+
238+
Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your source repository.
202239

203240
<Steps>
204-
205-
<Step title="Set Maven environment variables">
241+
<Step title="Set up authentication">
206242

207-
On your local machine, set the the following environment variable to the various tokens you generated in previous steps:
243+
Open your source repository in GitHub. Click on the **Settings** tab. Then, under the **Security** section, open **Secrets and variables** > **Actions**.
208244

209-
```bash
210-
export MAVEN_USERNAME=your-maven-username
211-
export MAVEN_PASSWORD=your-maven-password
212-
export MAVEN_SIGNATURE_SECRET_KEY_ID=your-gpg-key-id
213-
export MAVEN_SIGNATURE_PASSWORD=your-gpg-passphrase
214-
export MAVEN_SIGNATURE_SECRET_KEY=your-gpg-secret-key
215-
```
245+
You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.
246+
247+
</Step>
248+
<Step title="Add secret for your Fern Token">
249+
250+
1. Select **New repository secret**.
251+
1. Name your secret `FERN_TOKEN`.
252+
1. Add your Fern token. If you don't already have one, generate one by
253+
running `fern token`. By default, the `fern_token` is generated for the
254+
organization listed in `fern.config.json`.
255+
1. Click **Add secret**.
216256

217257
</Step>
258+
<Step title="Add secrets for Maven Central">
218259

219-
<Step title="Generate your release">
260+
Add the following repository secrets by selecting **New repository secret** for each:
220261

221-
Regenerate your SDK and publish it on Maven Central:
262+
1. `MAVEN_USERNAME` - Your Maven Central username
263+
1. `MAVEN_PASSWORD` - Your Maven Central password
264+
1. `MAVEN_SIGNATURE_SECRET_KEY_ID` - Your GPG key ID
265+
1. `MAVEN_SIGNATURE_PASSWORD` - Your GPG passphrase
266+
1. `MAVEN_SIGNATURE_SECRET_KEY` - Your GPG secret key
222267

223-
```bash
224-
fern generate --group java-sdk --version <version>
268+
</Step>
269+
<Step title="Set up a new workflow">
270+
271+
Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this:
272+
273+
```yaml title=".github/workflows/publish.yml" maxLines=0
274+
name: Publish Java SDK
275+
276+
on:
277+
workflow_dispatch:
278+
inputs:
279+
version:
280+
description: "The version of the Java SDK that you would like to release"
281+
required: true
282+
type: string
283+
284+
jobs:
285+
release:
286+
runs-on: ubuntu-latest
287+
steps:
288+
- name: Checkout repo
289+
uses: actions/checkout@v4
290+
291+
- name: Install Fern CLI
292+
run: npm install -g fern-api
293+
294+
- name: Release Java SDK
295+
env:
296+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
297+
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
298+
MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
299+
MAVEN_SIGNATURE_SECRET_KEY_ID: ${{ secrets.MAVEN_SIGNATURE_SECRET_KEY_ID }}
300+
MAVEN_SIGNATURE_PASSWORD: ${{ secrets.MAVEN_SIGNATURE_PASSWORD }}
301+
MAVEN_SIGNATURE_SECRET_KEY: ${{ secrets.MAVEN_SIGNATURE_SECRET_KEY }}
302+
run: |
303+
fern generate --group java-sdk --version ${{ inputs.version }} --log-level debug
225304
```
226-
Local machine output will verify that the release is pushed to your
227-
repository and tagged with the version you specified. Log back into Maven Central and
228-
navigate to **View Deployments** to see your new release.
229-
</Step>
305+
<Note>
306+
You can alternatively configure your workflow to execute `on: [push]`.
307+
</Note>
308+
</Step>
309+
310+
<Step title="Regenerate and release your SDK">
311+
312+
Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**. This regenerates your SDK.
313+
314+
<Markdown src="/products/sdks/snippets/release-sdk.mdx"/>
230315

231-
</Steps>
316+
Once the workflow completes, you can view your new release by logging into Maven Central and navigating to **View Deployments**.
317+
318+
</Step>
319+
320+
</Steps>
321+
322+
</Accordion>
323+
324+
<Accordion title="Release via CLI and environment variables">
325+
<Steps>
326+
327+
<Step title="Set Maven environment variables">
328+
329+
Set the Maven Central environment variables on your local machine:
330+
331+
```bash
332+
export MAVEN_USERNAME=your-maven-username
333+
export MAVEN_PASSWORD=your-maven-password
334+
export MAVEN_SIGNATURE_SECRET_KEY_ID=your-gpg-key-id
335+
export MAVEN_SIGNATURE_PASSWORD=your-gpg-passphrase
336+
export MAVEN_SIGNATURE_SECRET_KEY=your-gpg-secret-key
337+
```
338+
339+
</Step>
340+
<Step title="Regenerate and release your SDK">
341+
342+
Regenerate your SDK, specifying the version:
343+
344+
```bash
345+
fern generate --group java-sdk --version <version>
346+
```
347+
348+
<Markdown src="/products/sdks/snippets/release-sdk.mdx"/>
349+
350+
Once the command completes, you can view your new release by logging into Maven Central and navigating to **View Deployments**.
351+
352+
</Step>
353+
354+
</Steps>
355+
</Accordion>
356+
</AccordionGroup>

0 commit comments

Comments
 (0)