Self-hosted SDK versioning

When self-hosting, your pipeline picks the version number for each SDK release. Unlike cloud generation, self-hosted setups need to compute the next version themselves.

The CLI exposes two workflows for this. Both can be wired into the same generation pipeline:

• --version AUTO is the recommended approach. Fern classifies the change against the full SDK output — so changes driven by generators.yml settings, a generator version bump, or a CLI version bump are reflected in the version it picks — and writes the changelog entry, PR description, and conventional-commit message for you. This is also the path that continues to receive improvements.
• fern ir + fern diff is the deterministic alternative. It compares the intermediate representation (IR) of your API spec and returns only the computed bump and next version. Because the diff is over the spec alone, it doesn’t account for SDK-implementation changes that come from generators.yml configuration, generator version, or CLI version — if any of those move, you’ll need to bump the version yourself. The rest of the release artifacts (changelog, PR description, commit message) are also yours to write. Use this flow when you need explicit control over how the version number is derived, or when you can’t depend on an external LLM provider.

--version AUTO (recommended)

Pass --version AUTO to fern generate and Fern analyzes the diff between the previous and current SDK output, classifies the change as MAJOR, MINOR, or PATCH, and applies the next semantic version to the generated package. The same analysis also produces:

• A changelog entry describing what changed
• A PR description summarizing the release
• A conventional commit message

1
ai:
2
  provider: openai   # openai | anthropic | bedrock
3
  model: gpt-4o      # any model name the provider accepts

$
FERN_TOKEN=<token> fern generate --local --version AUTO

Deterministic versioning with fern ir + fern diff

If you’d rather derive the version number yourself, use the fern ir and fern diff commands to compute the bump from your API definition. This flow has no LLM dependency: fern diff walks the intermediate representation (IR) of both specs and returns a deterministic result.

The workflow has three steps:

$
fern ir old-ir.json

$
fern ir new-ir.json

$
fern diff \
>
  --from old-ir.json \
>
  --to new-ir.json \
>
  --from-version 1.4.2

1
{
2
  "bump": "minor",
3
  "nextVersion": "1.5.0",
4
  "errors": []
5
}

$
fern generate --local --version 1.5.0

Wiring fern ir + fern diff into CI

The non-obvious part is reproducing the IR for the previous spec. Each generated SDK records the config repo commit it was generated from in .fern/metadata.json:

1
{
2
  "cliVersion": "0.74.0",
3
  "generatorName": "fernapi/fern-python-sdk",
4
  "generatorVersion": "4.0.0",
5
  "originGitCommit": "a1b2c3d4e5f6...",
6
  "requestedVersion": "1.4.2",
7
  "sdkVersion": "1.4.2"
8
}

originGitCommit is the SHA in the config repo that produced the SDK at its current version. Check that commit out, run fern ir, then switch back to HEAD and run fern ir again to produce both inputs to fern diff.

1
name: Release SDK
2
3
on:
4
  push:
5
    branches: [main]
6
7
jobs:
8
  release:
9
    runs-on: ubuntu-latest
10
    env:
11
      FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
12
      SDK_REPO: your-org/python-sdk
13
    steps:
14
      - name: Check out config repo
15
        uses: actions/checkout@v4
16
        with:
17
          fetch-depth: 0
18
19
      - name: Set up Fern CLI
20
        uses: fern-api/setup-fern-cli@v1
21
22
      - name: Read previous SDK metadata
23
        id: meta
24
        run: |
25
          curl -fsSL \
26
            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
27
            -H "Accept: application/vnd.github.raw" \
28
            "https://api.github.com/repos/${SDK_REPO}/contents/.fern/metadata.json" \
29
            > metadata.json
30
          echo "old_sha=$(jq -r .originGitCommit metadata.json)" >> "$GITHUB_OUTPUT"
31
          echo "from_version=$(jq -r .sdkVersion metadata.json)" >> "$GITHUB_OUTPUT"
32
33
      - name: Generate previous IR
34
        run: |
35
          git checkout ${{ steps.meta.outputs.old_sha }}
36
          fern ir old-ir.json --api <your-api-name>
37
38
      - name: Generate current IR
39
        run: |
40
          git checkout ${{ github.sha }}
41
          fern ir new-ir.json --api <your-api-name>
42
43
      - name: Compute next version
44
        id: diff
45
        run: |
46
          result=$(fern diff \
47
            --from old-ir.json \
48
            --to new-ir.json \
49
            --from-version ${{ steps.meta.outputs.from_version }}) || true
50
          bump=$(echo "$result" | jq -r .bump)
51
          if [ "$bump" = "major" ]; then
52
            echo "Computed a major version bump — manual review required before releasing."
53
            exit 1
54
          fi
55
          echo "next_version=$(echo "$result" | jq -r .nextVersion)" >> "$GITHUB_OUTPUT"
56
57
      - name: Generate SDK
58
        run: fern generate --local --group python-sdk --version ${{ steps.diff.outputs.next_version }}