Skip to content
Platform Status

CLI

Workflow matrix

Tip

To quickly set up the workflow, run speakeasy configure github in the root of the SDK repository. This automates the setup and commits the necessary files. For more complex or custom configurations, the following is supported.

Workflow inputs

Section titled “Workflow inputs”
"on":
  workflow_dispatch:
    inputs:
      force:
        description: Force generation of SDKs
        type: boolean
        default: false
      set_version:
        description: optionally set a specific SDK version
        type: string
      runs-on:
        description: Runner to use for the workflow (e.g., large-ubuntu-runner)
        type: string
        default: ubuntu-latest

The inputs to the workflow determine how the SDKs will be generated.

Input Name
speakeasy_version
Description
Version of the Speakeasy CLI to use. Use "latest" to always use the latest version.
Default
latest
Type
string
mode
Description
Workflow mode: direct commits changes directly to the branch and publishes SDKs to configured package registries in the same run, pr creates a pull request (publishing is handled by the separate sdk_publish.yaml workflow when the PR is merged), or test fully runs through generation without modifying any GitHub state.
Default
direct
Type
string
force
Description
Forces SDK generation, even if no changes are detected.
Default
false
Type
boolean
set_version
Description
Manually set a specific version for the SDK being generated.
Default
None
Type
string

Workflow jobs

Section titled “Workflow jobs”

The generate job utilizes the Speakeasy SDK generation action. It references the workflow-executor.yaml from the sdk-generation-action repo, which handles the core operations like pulling the OpenAPI document, validating it, and generating the SDKs.

In direct mode, this workflow also handles publishing the generated SDKs to package registries (npm, PyPI, Maven, etc.) as part of the same run. In pr mode, publishing is handled separately by the sdk_publish.yaml workflow after the generated PR is merged.

With

Section titled “With”
jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
    with:
      force: ${{ github.event.inputs.force }}
      mode: pr
      set_version: ${{ github.event.inputs.set_version }}
      speakeasy_version: latest
      github_repository: acme-org/acme-sdk-typescript
      runs-on: ${{ github.event.inputs.runs-on }}
Input Name
speakeasy_version
Description
Version of the Speakeasy CLI to use. Use "latest" to always use the latest version.
Default
latest
Type
string
mode
Description
Workflow mode: direct commits changes directly to the branch and publishes SDKs to configured package registries in the same run, pr creates a pull request (publishing is handled by the separate sdk_publish.yaml workflow when the PR is merged), or test fully runs through generation without modifying any GitHub state.
Default
direct
Type
string
force
Description
Forces SDK generation, even if no changes are detected.
Default
false
Type
boolean
set_version
Description
Manually set a specific version for the SDK being generated.
Default
None
Type
string
github_repository
Description
The GitHub repository path (e.g., 'owner/repo-name') that package registries should reference. This overrides the default repository detected from the current Git context.
Default
None
Type
string
runs-on
Description
Specifies the runner to use for the workflow. Use this to configure larger GitHub-hosted runners for resource-intensive builds. Accepts runner labels like 'ubuntu-latest' or custom labels for larger runners.
Default
ubuntu-latest
Type
string

Secrets

Section titled “Secrets”
secrets:
  github_access_token: ${{ secrets.GITHUB_TOKEN }}
  npm_token: ${{ secrets.NPM_TOKEN }}
  speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
Secret Name
github_access_token
Description
GitHub access token with write access to the repository. Used to push changes and create PRs.
speakeasy_api_key
Description
API key for authenticating with the Speakeasy CLI.
npm_token
Description
Token to authenticate publishing to npm registry.
pypi_token
Description
Token to authenticate publishing to PyPi for Python packages.
packagist_token
Description
Token to authenticate publishing to Packagist for PHP packages.
ossrh_username
Description
Username for publishing the Java package to Sonatype Central Portal.
ossrh_password
Description
Password for publishing the Java package to Sonatype Central Portal.
java_gpg_secret_key
Description
GPG secret key used for signing the Java package.
java_gpg_passphrase
Description
Passphrase for the GPG secret key.
rubygems_auth_token
Description
Auth token (API key) for publishing to RubyGems.
nuget_api_key
Description
API key for publishing to the Nuget registry.
slack_webhook_url
Description
Optional: Slack Webhook URL for posting workflow failure notifications.
terraform_gpg_secret_key
Description
GPG secret key used for signing the Terraform provider.
terraform_gpg_passphrase
Description
Passphrase for the Terraform GPG secret key.

PyPI trusted publishing job

Section titled “PyPI trusted publishing job”

For Python SDKs using trusted publishing, add a publish-pypi job that runs after the main publish job. This job uses OIDC to authenticate with PyPI, eliminating the need for a PYPI_TOKEN secret.

publish-pypi:
  needs: publish
  if: ${{ needs.publish.outputs.python_regenerated == 'true' &&
          needs.publish.outputs.publish_python == 'true' &&
          needs.publish.outputs.use_pypi_trusted_publishing == 'true' }}
  runs-on: ubuntu-latest
  permissions:
    id-token: write
    contents: read
  steps:
    - uses: actions/checkout@v4
    - uses: speakeasy-api/sdk-generation-action/publish-pypi@v15
      with:
        python-directory: ${{ needs.publish.outputs.python_directory }}
        speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
        github_access_token: ${{ secrets.GITHUB_TOKEN }}
Input Name
python-directory
Description
Directory where the Python SDK was generated. Passed from the publish job outputs.
Default
None
Type
string
speakeasy_api_key
Description
API key for authenticating with the Speakeasy CLI.
Default
None
Type
string
github_access_token
Description
GitHub access token. Use the built-in GITHUB_TOKEN secret.
Default
None
Type
string

Important

The id-token: write permission is required at the job level for the OIDC token exchange with PyPI. The trusted publisher must also be configured on pypi.org for the target package.

Workflow outputs

Section titled “Workflow outputs”

The workflow provides outputs that indicate which SDKs were regenerated and can trigger further actions in the pipeline, such as validating, testing, and publishing the SDKs.

Output Name
python_regenerated
Description
Indicates if the Python SDK was regenerated.
python_directory
Description
Directory where the Python SDK was generated.
typescript_regenerated
Description
Indicates if the TypeScript SDK was regenerated.
typescript_directory
Description
Directory where the TypeScript SDK was generated.
java_regenerated
Description
Indicates if the Java SDK was regenerated.
java_directory
Description
Directory where the Java SDK was generated.
go_regenerated
Description
Indicates if the Go SDK was regenerated.
go_directory
Description
Directory where the Go SDK was generated.
php_regenerated
Description
Indicates if the PHP SDK was regenerated.
php_directory
Description
Directory where the PHP SDK was generated.
ruby_regenerated
Description
Indicates if the Ruby SDK was regenerated.
ruby_directory
Description
Directory where the Ruby SDK was generated.
terraform_regenerated
Description
Indicates if the Terraform SDK was regenerated.
terraform_directory
Description
Directory where the Terraform SDK was generated.
docs_regenerated
Description
Indicates if the SDK documentation was regenerated.
branch_name
Description
The branch name used for generating the SDK or the PR.
commit_hash
Description
The commit hash generated for the SDK (in direct mode).
publish_python
Description
Indicates if the Python SDK should be published.
use_pypi_trusted_publishing
Description
Indicates if PyPI trusted publishing is configured for the Python SDK.