Publishing to PyPI

Configure OIDC

sdk-config.yml supports trusted publishing only for npm. To add token: OIDC with generators.yml, see Legacy PyPI publishing.

Generate your SDK

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

fern generate --target python

This creates a .github/workflows/ci.yml file that’s configured to use OIDC for PyPI publishing.

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 sdk-config.yml

Add your PyPI token to output.publish. PyPI API tokens use __token__ as the username:

targets:
  - language: python
    package:
      packageName: your-package-name
    generation:
      naming:
        clientName: YourClientName
    output:
      delivery: github
      github:
        repository: your-org/your-repository
        mode: push
        branch: your-branch-name
      publish:
        registry: pypi
        username: __token__
        password: ${PYPI_TOKEN}

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:

name: Publish Python SDK
on:
  workflow_dispatch:
    inputs:
      version:
        description: "The version of the Python SDK that you would like to release"
        required: true
        type: string
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install Fern CLI
        run: npm install -g fern-api
      - name: Release Python SDK
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} # Only needed for token-based authentication
        run: |
          fern generate --target python --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 --target python --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.