> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification. > > GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJmMTI5YTFkOC0wYTBmLTQyOGYtYjRlZC1iZWFjMGVmNWZmNDMiLCJleHAiOjE3Nzk5NjE3MzksImlhdCI6MTc3OTk2MTQzOX0._2zgIZ3jGeHnnEHiBSO6XEs1jfaOt5W__Y9zzJhsROs > > For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt. # Self-hosted SDK versioning > Compute the next SDK version number from your own CI when self-hosting Fern SDK generation. This feature is available only for the [Enterprise plan](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com). When self-hosting, your pipeline picks the version number for each SDK release. Unlike cloud generation, [self-hosted setups](/learn/sdks/deep-dives/self-hosted) 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](https://semver.org/) to the generated package. The same analysis also produces: * A changelog entry describing what changed * A PR description summarizing the release * A [conventional commit](https://www.conventionalcommits.org/) message `--version AUTO` requires: * A `FERN_TOKEN` for organization verification (same as all self-hosted generation). * A [GitHub output](/learn/sdks/deep-dives/self-hosted#setup) configured in `generators.yml`, since the pipeline pushes the version bump and changelog back to the SDK repo. Set the provider and model in `generators.yml`: ```yaml title="generators.yml" ai: provider: openai # openai | anthropic | bedrock model: gpt-4o # any model name the provider accepts ``` Export the matching API key so the Fern CLI can call the provider: * `OPENAI_API_KEY` for OpenAI * `ANTHROPIC_API_KEY` for Anthropic * Standard AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`) for AWS Bedrock The diff is sent to the provider's API using your credentials — Fern's infrastructure is not involved in the analysis. ```bash FERN_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: Check out the spec as it was at the last SDK generation and write its IR to disk: ```bash fern ir old-ir.json ``` Pass `--api ` if your [project defines multiple APIs](/learn/sdks/overview/project-structure). Check out the spec at `HEAD` and write its IR to disk: ```bash fern ir new-ir.json ``` Run `fern diff` with `--from-version` set to the SDK's current version. When `--from-version` is provided, the command prints a JSON object containing the computed bump and the next version: ```bash fern diff \ --from old-ir.json \ --to new-ir.json \ --from-version 1.4.2 ``` ```json { "bump": "minor", "nextVersion": "1.5.0", "errors": [] } ``` `bump` is one of `major`, `minor`, `patch`, or `no_change`. Pass `nextVersion` to `fern generate` to release that exact version: ```bash fern generate --local --version 1.5.0 ``` ```bash fern generate --local --output-version 1.5.0 ``` `fern diff` exits with a non-zero status when the computed bump is `major`. This makes it easy to gate breaking changes on a manual review step in CI. ### 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`: ```json title=".fern/metadata.json" { "cliVersion": "0.74.0", "generatorName": "fernapi/fern-python-sdk", "generatorVersion": "4.0.0", "originGitCommit": "a1b2c3d4e5f6...", "requestedVersion": "1.4.2", "sdkVersion": "1.4.2" } ``` `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`. The following snippet runs in the config repo on every push to `main` and computes the next version for a Python SDK whose `originGitCommit` and `sdkVersion` are read from the SDK repo: ```yaml title=".github/workflows/release-sdk.yml" name: Release SDK on: push: branches: [main] jobs: release: runs-on: ubuntu-latest env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} SDK_REPO: your-org/python-sdk steps: - name: Check out config repo uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Fern CLI uses: fern-api/setup-fern-cli@v1 - name: Read previous SDK metadata id: meta run: | curl -fsSL \ -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \ -H "Accept: application/vnd.github.raw" \ "https://api.github.com/repos/${SDK_REPO}/contents/.fern/metadata.json" \ > metadata.json echo "old_sha=$(jq -r .originGitCommit metadata.json)" >> "$GITHUB_OUTPUT" echo "from_version=$(jq -r .sdkVersion metadata.json)" >> "$GITHUB_OUTPUT" - name: Generate previous IR run: | git checkout ${{ steps.meta.outputs.old_sha }} fern ir old-ir.json --api - name: Generate current IR run: | git checkout ${{ github.sha }} fern ir new-ir.json --api - name: Compute next version id: diff run: | result=$(fern diff \ --from old-ir.json \ --to new-ir.json \ --from-version ${{ steps.meta.outputs.from_version }}) || true bump=$(echo "$result" | jq -r .bump) if [ "$bump" = "major" ]; then echo "Computed a major version bump — manual review required before releasing." exit 1 fi echo "next_version=$(echo "$result" | jq -r .nextVersion)" >> "$GITHUB_OUTPUT" - name: Generate SDK run: fern generate --local --group python-sdk --version ${{ steps.diff.outputs.next_version }} ``` `fetch-depth: 0` on the checkout step is required so the runner has the history needed to check out `originGitCommit`. Replace the metadata-fetch step with whatever mechanism gives your pipeline access to the SDK repo's `.fern/metadata.json` (a checkout of the SDK repo, a release artifact, an internal API, and so on).