SDK versioning

Speakeasy-generated SDKs are automatically versioned using Semantic Versioning (SemVer (opens in a new tab)). Every time an SDK is generated (or regenerated), its version is bumped up.

Versioning logic

The SDK version is incremented automatically in the following cases.

Generator version changes

When Speakeasy releases a new generator version, it compares the features changed in the new generator to those used in the SDK:

If more than one of the features used in the SDK has changed, the largest version bump (major, minor, or patch) across all the features determines the increment by which the overall version is bumped.
Features unaffected by the new generator version maintain the current version.

Configuration changes

The patch version is bumped for the following configuration changes:

Changes to the gen.yaml file.
Changes to the checksum.

OpenAPI document changes

As long as the info.version section of your OpenAPI document is SemVer compliant:

Major changes to the OpenAPI document bump the major version of the SDK.
Minor changes to the OpenAPI document bump the minor version of the SDK.

Coming Soon: Speakeasy will detect changes to the OpenAPI document (for example, if a breaking change is added to the parameters of an operation) and bump the SDK versions accordingly.

Pre-release version bumps

Speakeasy supports any SemVer-compatible string as a valid version, including pre-release versions such as X.X.X-alpha or X.X.X-alpha.X.

Pre-release versioning continues until manual removal.
Automated bumps increment pre-release versions. For example, 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-alpha.2.
To exit pre-release versioning, set a new version or run speakeasy bump graduate.

Major version bumps

New SDKs start at version 0.0.1. Automatic major version bumps begin after the SDK reaches version 1.0.0. Breaking changes trigger major version increments after version 1.0.0.

Major version changes affect the Golang SDK migration path.

Go major version bumps

For Go module versions above v1.0.0, the major version must be included in the import path. For example:

Version 1.2.3: github.com/speakeasy/speakeasy-go
Version 2.0.0: github.com/speakeasy/speakeasy-go/v2

Carefully consider major version changes to Go SDKs, as they can significantly impact migration paths. The SDK maintainer determines when major versions are incremented.

Manual version bumps

You can manually control SDK versioning via the Speakeasy CLI, the GitHub UI, or the Speakeasy dashboard.

Via the Speakeasy CLI

To override the automatic versioning logic for the next generation of an SDK, set the version field in the gen.yaml file.

The Speakeasy generator detects manual version settings when the releaseVersion field in the gen.lock file differs from the version field in the gen.yaml file.
Automatic versioning resumes when the version values in both files match.

You can also use the Speakeasy CLI bump command to set the SDK version without manually editing the gen.yaml file.

Via the GitHub UI

Speakeasy supports label-based versioning via the GitHub pull request (PR) UI, which provides the following:

Automated version detection: The system analyzes changes and suggests the appropriate semantic version bump. The generated PR displays a suggested version label - major, minor, or patch. A pre-release label is also added for pre-release versions.
Manual override option: You can override the suggestion by removing the current label and adding a major, minor, or patch label to the PR. Use the bump type graduate to move out of the pre-release stage. The SDK version updates automatically on the next generation and persists across regenerations until changed.

https://github.com/speakeasy-sdks/bar-python/pull/8

Immediate generation: Label-based versioning is active in all SDK generation workflows. To automate generation immediately after label addition, add the following action trigger to the GitHub workflow file (typically at .github/workflows/sdk_generation.yaml):

name: Generate
permissions:
    checks: write
    contents: write
    pull-requests: write
    statuses: write
"on":
    workflow_dispatch:
        inputs:
            force:
                description: Force generation of SDKs
                type: boolean
                default: false
            push_code_samples_only:
                description: Force-push only code samples from SDK generation
                type: boolean
                default: false
            set_version:
                description: Optionally set a specific SDK version
                type: string
    pull_request:
        types: [labeled]
    schedule:
        - cron: 0 0 * * *

Via the Speakeasy dashboard

Follow these steps to set a version manually in the Speakeasy dashboard:

Navigate to the Publishing tab and select Set a New Version.

https://app.speakeasy.com/org/
Enter the version according to the SemVer conventions. The dashboard validates the version and ensures there is no version override.

https://app.speakeasy.com/org/
Click Submit Version Change to apply the new version.