diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 7af037cdc..e444fef52 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -108,3 +108,5 @@ exceptions: - SPDX - BCP - ISO + - AUTO + - SHA diff --git a/fern/products/sdks/deep-dives/self-hosted-versioning.mdx b/fern/products/sdks/deep-dives/self-hosted-versioning.mdx new file mode 100644 index 000000000..1d41c4064 --- /dev/null +++ b/fern/products/sdks/deep-dives/self-hosted-versioning.mdx @@ -0,0 +1,213 @@ +--- +title: Self-hosted SDK versioning +description: Compute the next SDK version number from your own CI when self-hosting Fern SDK generation. +--- + + + +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, picks the next version, 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 returns only the computed bump and next version — the rest of the release artifacts are yours to write. Use it 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 --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 --version 1.5.0 +``` + + +```bash +fern generate --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 --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). + + diff --git a/fern/products/sdks/deep-dives/self-hosted.mdx b/fern/products/sdks/deep-dives/self-hosted.mdx index f4f4d9a97..4567ee772 100644 --- a/fern/products/sdks/deep-dives/self-hosted.mdx +++ b/fern/products/sdks/deep-dives/self-hosted.mdx @@ -13,7 +13,7 @@ Fern SDK generation [runs on Fern's infrastructure by default](/sdks/overview/ho - Has strict compliance or security requirements - Needs full control over your SDK generation process -When you self-host, you're responsible for infrastructure management and SDK distribution. Self-hosted SDK generation includes [all Fern SDK features](/learn/sdks/overview/capabilities). +When you self-host, you're responsible for infrastructure management, SDK distribution, and [computing SDK version numbers](/learn/sdks/deep-dives/self-hosted-versioning). Self-hosted SDK generation includes [all Fern SDK features](/learn/sdks/overview/capabilities). Unless you have specific requirements that prevent using Fern's default hosting, we recommend **using our managed cloud generation solution** for easier setup and maintenance. @@ -120,6 +120,12 @@ Set up GitHub secrets for authentication. In your repository's **Settings** > ** + + +Cloud generation picks SDK version numbers automatically. With self-hosting, your pipeline computes the next version itself — see [Self-hosted SDK versioning](/learn/sdks/deep-dives/self-hosted-versioning) for the two supported workflows. + + + Use the `--local` flag to generate SDKs locally instead of using Fern's cloud infrastructure. You can combine `--local` with `--group` to generate specific SDKs locally. diff --git a/fern/products/sdks/sdks.yml b/fern/products/sdks/sdks.yml index 2e9f95fc9..1fc3b9540 100644 --- a/fern/products/sdks/sdks.yml +++ b/fern/products/sdks/sdks.yml @@ -256,13 +256,16 @@ navigation: - page: Testing path: ./deep-dives/testing.mdx slug: testing - - section: Hosting + - section: Self-hosting slug: deep-dives collapsed: true contents: - - page: Self-hosted SDKs + - page: Setup path: ./deep-dives/self-hosted.mdx slug: self-hosted + - page: Versioning + path: ./deep-dives/self-hosted-versioning.mdx + slug: self-hosted-versioning - section: Reference contents: - page: generators.yml