Skip to content

Add info on setting up GitHub repos and configuring GitHub Actions for npm publishing #203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jul 30, 2025
+218 −74
Merged

Add info on setting up GitHub repos and configuring GitHub Actions for npm publishing #203

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
258c8b0
page setup for github guide
devalog Jul 23, 2025
b3877a3
merge
devalog Jul 28, 2025
f82cdb2
add github actions workflow for npm publishing page
devalog Jul 28, 2025
c54c826
add github architecture doc and edit npm publishing guide
devalog Jul 28, 2025
1947262
edit github structure page
devalog Jul 28, 2025
aa8d9c2
edit language and links
devalog Jul 28, 2025
18509f9
remove manual github actions step
devalog Jul 30, 2025
303a40c
Merge branch 'main' into github-setup
devalog Jul 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 3 additions & 18 deletions fern/products/sdks/fern-folder.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,24 +30,9 @@ in different languages.
{/* <Markdown src="/products/sdks/snippets/option-3-asyncapi.mdx"/> */}
</AccordionGroup>

### Generate an SDK in your desired language

<CardGroup cols={3}>
<Card title="TypeScript" icon={<img src="./images/icons/ts-light.svg" alt="TypeScript logo" className="h-6 w-6" noZoom />} href="/sdks/generators/typescript/quickstart">
</Card>
<Card title="Python" icon={<img src="./images/icons/python-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/python/quickstart">
</Card>
<Card title="Go" icon={<img src="./images/icons/go-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/go/quickstart">
</Card>
<Card title="Java" icon={<img src="./images/icons/java-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/java/quickstart">
</Card>
<Card title=".NET" icon={<img src="./images/icons/csharp-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/csharp/quickstart">
</Card>
<Card title="PHP" icon={<img src="./images/icons/php-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/php/quickstart">
</Card>
<Card title="Ruby" icon={<img src="./images/icons/ruby-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/php/quickstart">
</Card>
</CardGroup>
### Set up GitHub

Now, you're ready to [set up your GitHub repositories](/sdks/overview/github).

</Steps>

Expand Down
109 changes: 109 additions & 0 deletions fern/products/sdks/github-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
---
title: Structure your GitHub repositories
description: Set up GitHub repositories for your SDKs
---

Before generating SDKs with Fern, you'll need to set up the proper GitHub
repository structure to house your API definitions and SDK code so it's
intuitive for you and your users to access, maintain, and update code.

<Steps>
## Structuring your top-level repository

1. Identify or create a top-level GitHub repository where you want all of your
SDK and API code to live.
1. Install the [Fern GitHub App](https://github.com/apps/fern-api) on the
top-level repository and all SDK repositories. Select **Configure**, then
scroll down to **Repository Access**. Select **Only select repositories** and
in the dropdown select the repository for your SDK. Click **Save**.

For example, your basic GitHub file structure should look something like this:

```
├─ company-repo # Top-level repo for all SDKs
├─ fern/
├─ apis/
├─ sdks/
└── generators.yml # Contains settings for all SDKs
```
Your `generators.yml` file will contain a group for each of your SDKs. Each group points
to the GitHub repository for the relevant SDK.

For example, the `group` for a TypeScript SDK might look like this:

```yaml title="generators.yml"
ts-sdk:
generators:
- name: fernapi/fern-typescript-sdk
version: 2.6.3
github:
repository: your-organization/your-typescript-repo
```

For additional examples, see Cohere's [`generators.yml`
file](https://github.com/cohere-ai/cohere-developer-experience/blob/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern/apis/sdks/generators.yml)
and Vapi's [`generators.yml`
file](https://github.com/VapiAI/docs/blob/9c674c2b16ba03e864e26673c5290c88048c9a7a/fern/apis/api/generators.yml).

<Info>You can also additionally configure the `github` section to whether Fern
should commit and release, create a pull request, or push code to a branch when
you make changes to your SDK code. See [GitHub
Configuration](/sdks/reference/generators-yml#github-configuration) for more
details. </Info>

## Structuring SDK-specific repositories

1. Create a new GitHub repository called `company-<language>` (or something
similar) for each of your SDKs, if you haven't done so already.
1. Install the [Fern GitHub App](https://github.com/apps/fern-api) on the
top-level repository and all SDK repositories. Select **Configure**, then
scroll down to **Repository Access**. Select **Only select repositories** and
in the dropdown select the repository for your SDK. Click **Save**.


The repository structure for a specific SDK should look similar to this:

```{6-11}
├─ company-repo # Top-level repo for all SDKs
├─ fern/
├─ apis/
├─ sdks/
└── generators.yml # Contains settings for all SDKs
├─ typescript-sdk-repo # Repository for a TypeScript SDK
├─ .github/workflows/ # Contains GitHub Actions for publishing to package repositories, etc.
├─ scripts/
├─ src/
├─ tests/
└── .fernignore # Lists files that Fern shouldn't modify
├─ python-sdk-repo
└── go-sdk-repo
```

Fern generates most of the SDK files listed in this example repository (`scripts/`, `src/`, `tests`,
`.fernignore`, etc.), including any custom code you added. You have to manually set up `.github/workflows` to execute actions, like publishing SDK versions to a package repository.

For additional examples, see Cohere's [Python SDK repository](https://github.com/cohere-ai/cohere-python) and [Vapi's TypeScript SDK repository](https://github.com/VapiAI/server-sdk-typescript).

## Generate an SDK in your desired language

Once you've set up your GitHub repository structure, you can proceed with generating SDKs in your desired languages.

<CardGroup cols={3}>
<Card title="TypeScript" icon={<img src="./images/icons/ts-light.svg" alt="TypeScript logo" className="h-6 w-6" noZoom />} href="/sdks/generators/typescript/quickstart">
</Card>
<Card title="Python" icon={<img src="./images/icons/python-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/python/quickstart">
</Card>
<Card title="Go" icon={<img src="./images/icons/go-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/go/quickstart">
</Card>
<Card title="Java" icon={<img src="./images/icons/java-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/java/quickstart">
</Card>
<Card title=".NET" icon={<img src="./images/icons/csharp-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/csharp/quickstart">
</Card>
<Card title="PHP" icon={<img src="./images/icons/php-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/php/quickstart">
</Card>
<Card title="Ruby" icon={<img src="./images/icons/ruby-light.svg" className="h-6 w-6" noZoom />} href="/sdks/generators/php/quickstart">
</Card>
</CardGroup>

</Steps>

Binary file added fern/products/sdks/overview/typescript/assets/npm-token-secret.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
200 changes: 149 additions & 51 deletions fern/products/sdks/overview/typescript/publishing-to-npm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,52 +11,28 @@ you'll have a versioned package published on npm.
<img src="assets/npm-packages.png" alt="Versioned package published on npm" />
</Frame>

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

## Set up your GitHub integration
* An initialized `fern` folder on your local machine. See [Set up the `fern`
folder](/sdks/overview/quickstart).
* A GitHub repository for your TypeScript SDK. See [Set up your GitHub structure](/sdks/overview/github).
* A TypeScript generator group in `generators.yml`. See [TypeScript
Quickstart](quickstart#add-the-sdk-generator).

1. Create a new GitHub repository called `company-typescript` (or something similar) for your SDK, if you haven't done so already.
1. Install the [Fern GitHub App](https://github.com/apps/fern-api): Select **Configure**, then scroll down to **Repository Access**. Select **Only select repositories** and in the dropdown select the repository for your SDK. Click **Save**.

</Info>

## Configure `generators.yml`

<Steps>

<Step title="Run `fern add <generator>`">

Navigate to your `generators.yml` on your local machine. Your `generators.yml` lives inside of your `fern` folder and contains all the configuration for your Fern generators.

Add a new generator to `generators.yml`:


```bash
fern add fern-typescript-sdk --group ts-sdk
```

Once the command completes, you'll see a new group created in your `generators.yml`:

```yaml {3-9}
groups:
...
ts-sdk:
generators:
- name: fernapi/fern-typescript-sdk
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
output:
location: local-file-system
path: ../sdks/typescript
```

</Step>

<Step title="Configure `output` location">

Next, change the output location in `generators.yml` from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry:
In the `group` for your TypeScript SDK, change the output location in from `local-file-system` (the default) to `npm` to indicate that Fern should publish your package directly to the npm registry:

```yaml {6-7}
groups:
ts-sdk:
ts-sdk: # Group name for your TypeScript SDK
generators:
- name: fernapi/fern-typescript-sdk
version: <Markdown src="/snippets/typescript-sdk-version.mdx"/>
Expand Down Expand Up @@ -106,7 +82,7 @@ groups:

<Step title="Add repository location">

Add the path to your GitHub repository to `generators.yml`:
Add the path to your GitHub repository to `generators.yml`, if you haven't already:

```yaml {11-12}
groups:
Expand All @@ -126,7 +102,7 @@ groups:
</Step>
</Steps>

## Set up npm publishing authentication
## Generate an npm token

<Steps>

Expand Down Expand Up @@ -184,6 +160,136 @@ groups:

</Step>

</Steps>

## Configure npm authentication

<AccordionGroup>
<Accordion title="Option 1: Configure authentication via GitHub Actions">

Use [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) to automatically publish new SDK versions to npm when you push code changes.

<Steps>

<Step title="Navigate to Actions in Settings">

Open your Fern repository in GitHub. Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**.

<Frame>
<img src="assets/github-secret.png" alt="Adding GitHub Repository Secret" />
</Frame>

You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.

</Step>

<Step title="Add secret for your npm Token">

1. Select **New repository secret**.
1. Name your secret `NPM_TOKEN`.
1. Add the corresponding token you generated above.
1. Click **Add secret**.

<Frame>
<img src="assets/npm-token-secret.png" alt="NPM_TOKEN secret" />
</Frame>

</Step>

<Step title="Allow GitHub to run workflows">

Change your workflow permissions to allow GitHub to run workflows:

1. Click on the **Settings** tab in your repository.
1. Under the **Code and automation** section, navigate to **Actions** > **General**.
1. Under **Actions permissions**, select **Allow all actions and reusable workflows**.
1. **Save** your settings. Now GitHub can run the actions you configure.

</Step>
<Step title="Set up a publishing workflow">

Use GitHub Actions to set up a workflow that automatically publishes your new releases to npm.

To get started, navigate to the **Actions** tab in your repositiory and select **set up a workflow yourself**. GitHub will automatically set up a blank yml file in a new `.github/workflows` directory.
Copy link
Member

@Swimburger Swimburger Jul 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The generator should generate the CI file when npm output and token is specified in generators.yml


Rename this file `ci.yml`. Your file should look like this:

```yaml title=".github/workflows/ci.yml" maxLines=0
name: ci

on: [push]

jobs:
compile:
runs-on: ubuntu-latest

steps:
- name: Checkout repo
uses: actions/checkout@v4

- name: Set up node
uses: actions/setup-node@v3

- name: Compile
run: yarn && yarn build

test:
runs-on: ubuntu-latest

steps:
- name: Checkout repo
uses: actions/checkout@v4

- name: Set up node
uses: actions/setup-node@v3

- name: Compile
run: yarn && yarn test

publish:
needs: [ compile, test ]
if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v4
- name: Set up node
uses: actions/setup-node@v3
- name: Install dependencies
run: yarn install
- name: Build
run: yarn build

- name: Publish to npm
run: |
npm config set //registry.npmjs.org/:_authToken ${NPM_TOKEN}
if [[ ${GITHUB_REF} == *alpha* ]]; then
npm publish --access public --tag alpha
elif [[ ${GITHUB_REF} == *beta* ]]; then
npm publish --access public --tag beta
else
npm publish --access public
fi
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
```

For another example, see Vapi's [npm publishing GitHub Action](https://github.com/VapiAI/server-sdk-typescript/blob/main/.github/workflows/ci.yml)
</Step>

<Step title="Update `.fernignore`">
Copy link
Member

@Swimburger Swimburger Jul 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We shouldn't need to .fernignore this.

Once your workflow is configured, add your new workflow file to `.fernignore` so regenerating releases doesn't overwrite your workflow.

```diff title=".fernignore"
+ .github/workflows/ci.yml
```

</Step>
</Steps>

</Accordion>
<Accordion title="Option 2: Configure via environment variables">
<Steps>
<Step title="Configure npm authentication token">

Add `token: ${NPM_TOKEN}` to `generators.yml` to tell Fern to use the `NPM_TOKEN` environment variable for authentication when publishing to the npm registry.
Expand All @@ -204,15 +310,6 @@ groups:
repository: your-org/your-repository
```
</Step>

</Steps>

## Release your SDK to NPM

At this point, you're ready to generate a release for your SDK.

<Steps>

<Step title="Set npm environment variable">

Set the `NPM_TOKEN` environment variable on your local machine:
Expand All @@ -222,8 +319,13 @@ groups:
```

</Step>
</Steps>
</Accordion>
</AccordionGroup>



<Step title="Generate your release">
## Release your SDK to npm

Regenerate your SDK and publish it on npm:

Expand All @@ -232,8 +334,4 @@ groups:
```
Local machine output will verify that the release is pushed to your
repository and tagged with the version you specified. Log back into npm and
navigate to **Packages** to see your new release.

</Step>

</Steps>
navigate to **Packages** to see your new release.
Loading