Publishing to PyPI

Add OIDC to generators.yml

Add token: OIDC to the output section:

1
groups:
2
  python-sdk:
3
	generators:
4
	  - name: fern-python-sdk
5
		version: 5.16.1  # Must be 4.38.1 or later
6
		output:
7
		  location: pypi
8
		  package-name: your-package-name
9
		  token: OIDC
10
	config:
11
	  client_class_name: YourClientName
12
	github:
13
	  repository: your-org/your-repository
14
	  mode: push
15
	  branch: your-branch-name

Generate your SDK

Generate your SDK to create the GitHub Actions workflow with OIDC configuration:

$
fern generate --group python-sdk

This creates a .github/workflows/ci.yml file that’s configured to use OIDC for PyPI publishing. Alternatively, you can push your generators.yml changes and let the Fern GitHub Action generate the workflow for you.

Authorize your repository on PyPI

Configure trusted publishing on PyPI to allow your GitHub repository to publish:

1. Navigate to your project on PyPI and open Manage > Publishing
2. Under Add a new publisher, select GitHub
3. Fill in:
   • Owner: Your GitHub username or organization
   • Repository name: Your Python SDK repository name (e.g., your-repository)
   • Workflow name: ci.yml
   • Environment name: pypi

For more details, see PyPI’s trusted publishers documentation.

Generate a PyPI token

1. Log into PyPI or create a new account
2. Click on your profile picture and select Account settings
3. Scroll down to API tokens and click Add API token
4. Name your token and set the scope to the relevant projects
5. Click Create token

Add token to generators.yml

Add token: ${PYPI_TOKEN} to the output section:

1
groups: 
2
  python-sdk:
3
    generators:
4
      - name: fern-python-sdk
5
        version: 5.16.1
6
        output:
7
          location: pypi
8
          package-name: your-package-name
9
          token: ${PYPI_TOKEN}
10
        config:
11
          client_class_name: YourClientName
12
        github: 
13
          repository: your-org/your-repository

Add PYPI_TOKEN as a GitHub Actions secret

1. Open your repository on GitHub and go to Settings
2. Navigate to Secrets and variables > Actions
3. Click New repository secret
4. Name it PYPI_TOKEN and paste your PyPI token
5. Click Add secret

Add secret for your Fern API key

1. Open your Fern repository on GitHub and go to Settings > Secrets and variables > Actions
2. Select New repository secret
3. Name your secret FERN_TOKEN
4. Add your Fern API key. If you don’t already have one, generate one by running fern token. By default, the API key is generated for the organization listed in fern.config.json.
5. Click Add secret

If you use token-based authentication, also add a PYPI_TOKEN secret with your PyPI token.

Set up a new workflow

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:

1
name: Publish Python SDK
2
3
on:
4
  workflow_dispatch:
5
    inputs:
6
      version:
7
        description: "The version of the Python SDK that you would like to release"
8
        required: true
9
        type: string
10
11
jobs:
12
  release:
13
    runs-on: ubuntu-latest
14
    steps:
15
      - name: Checkout repo
16
        uses: actions/checkout@v4
17
18
      - name: Install Fern CLI
19
        run: npm install -g fern-api
20
21
      - name: Release Python SDK
22
        env:
23
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
24
          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} # Only needed for token-based authentication
25
        run: |
26
          fern generate --group python-sdk --version ${{ inputs.version }} --log-level debug

Regenerate and release your SDK

Navigate to the Actions tab, select the workflow you just created, specify a version number, and click Run workflow. This regenerates your SDK.

The rest of the release process depends on your chosen mode:

• Release mode (default): If you didn’t specify a mode or set mode: release, no further action is required. Fern automatically tags the new release with your specified version number and initiates the publishing workflow in your SDK repository.

• Pull request or push mode: If you set mode: pull-request or mode: push, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (pull-request) or branch (push), then tag a new release to initiate the publishing workflow in your SDK repository.

Once the workflow completes, you can view your new release by logging into PyPi and navigating to Your projects.

Set PyPI environment variable

If you use token-based authentication, set the PYPI_TOKEN environment variable on your local machine:

$
export PYPI_TOKEN=your-actual-pypi-token

Regenerate and release your SDK

Regenerate your SDK, specifying the version:

$
fern generate --group python-sdk --version <version>

The rest of the release process depends on your chosen mode:

• Release mode (default): If you didn’t specify a mode or set mode: release, no further action is required. Fern automatically tags the new release with your specified version number and initiates the publishing workflow in your SDK repository.

• Pull request or push mode: If you set mode: pull-request or mode: push, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (pull-request) or branch (push), then tag a new release to initiate the publishing workflow in your SDK repository.

Once the workflow completes, you can view your new release by logging into PyPI and navigating to Your projects.

Configure trusted publishing on PyPI

1. Navigate to your project on PyPI and open Manage > Publishing
2. Under Add a new publisher, select GitHub
3. Fill in:
   • Owner: Your GitHub username or organization
   • Repository name: Your Python SDK repository name
   • Workflow name: ci.yml
   • Environment name: pypi

For more details, see PyPI’s trusted publishers documentation.

Update your generators.yml

Change the output.token field from ${PYPI_TOKEN} to OIDC and ensure you’re using version 4.38.1 or later:

1
groups:
2
  python-sdk:
3
	generators:
4
	  - name: fern-python-sdk
5
		version: 5.16.1  # Must be 4.38.1 or later
6
		output:
7
		  location: pypi
8
		  package-name: your-package-name
9
		  token: OIDC  # Changed from ${PYPI_TOKEN}
10
	config:
11
	  client_class_name: YourClientName
12
	github:
13
	  repository: your-org/your-repository

Regenerate your SDK

Regenerate the SDK to update the CI workflow with OIDC configuration:

Locally:

$
fern generate --group python-sdk

Or via GitHub Actions:

Push your updated generators.yml and let the Fern GitHub Action regenerate the SDK.

This updates .github/workflows/ci.yml with the required OIDC permissions and switches to the pypa/gh-action-pypi-publish action.

Remove the PYPI_TOKEN secret

After verifying the migration works, remove the PYPI_TOKEN secret from your GitHub repository settings (Settings > Secrets and variables > Actions).

Configure trusted publishing on PyPI

Follow the same instructions as Path 1 to add your repository as a trusted publisher on PyPI.

Add a build job to your CI workflow

Open .github/workflows/ci.yml and add a build job that builds and uploads your package as an artifact:

1
  build:
2
	name: Build distribution
3
	runs-on: ubuntu-latest
4
	steps:
5
	  - name: Checkout repo
6
		uses: actions/checkout@v4
7
	  - name: Set up python
8
		uses: actions/setup-python@v4
9
		with:
10
		  python-version: "3.9"
11
	  - name: Bootstrap poetry
12
		run: |
13
		  curl -sSL https://install.python-poetry.org | python - -y --version 1.5.1
14
	  - name: Install dependencies
15
		run: poetry install
16
	  - name: Build package
17
		run: poetry build
18
	  - name: Store the distribution packages
19
		uses: actions/upload-artifact@v4
20
		with:
21
		  name: python-package-distributions
22
		  path: dist/

Replace the publish job

Replace your existing publish job with the OIDC-based version:

1
  publish:
2
	name: Publish to PyPI
3
	needs: [compile, test, build]
4
	if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
5
	runs-on: ubuntu-latest
6
	environment:
7
	  name: pypi
8
	  url: https://pypi.org/p/${{ github.event.repository.name }}
9
	permissions:
10
	  contents: read   # Required for checkout
11
	  id-token: write  # Required for OIDC
12
	steps:
13
	  - name: Download all the dists
14
		uses: actions/download-artifact@v4
15
		with:
16
		  name: python-package-distributions
17
		  path: dist/
18
	  - name: Publish to PyPI
19
		uses: pypa/gh-action-pypi-publish@release/v1
20
		with:
21
		  repository-url: https://upload.pypi.org/legacy/

Key changes from token-based publishing:

• Adds environment block pointing to pypi
• Adds permissions with id-token: write and contents: read
• Replaces poetry publish with pypa/gh-action-pypi-publish@release/v1
• Removes all env blocks referencing PYPI_TOKEN or PYPI_PASSWORD

(Optional) Add ci.yml to .fernignore

Prevent future generator updates from overwriting your manual changes:

.github/workflows/ci.yml

Remove the PYPI_TOKEN secret

After verifying the migration works, remove the PYPI_TOKEN secret from your GitHub repository settings.