SDK Generation Action and Workflows

The sdk-generation-action repository (opens in a new tab) provides an action and workflows to generate client SDKs from an OpenAPI document using the Speakeasy CLI (opens in a new tab). You can use the action and workflows to manage CI/CD (that is, the automatic generation and publishing of client SDKs) in a repo containing the generated SDKs.

Find more information about the Speakeasy Client SDK Generator for OpenAPI Documents in the SDK creation overview.

The workflows included in the Speakeasy SDK Generation Action give you options for publishing the generated SDKs to various package managers on the successful completion of the action. An SDK can be published via PR or directly to the repo.

The action is a self-contained solution to automatically generate new versions of a client SDK when the reference OpenAPI doc or the Speakeasy CLI generating the SDK is updated.

You can use the action to:

  • Run a validation check on an OpenAPI doc. This is known as the validate action.
  • Generate an SDK and commit it directly to a branch in the repo such as main or master. This mode is known as the generate action in direct mode.
  • Generate an SDK and commit it to an autogenerated branch, then create a PR to merge the changes back into the main repo. This mode is known as the generate action in pr mode.
  • Apply suggestions to an OpenAPI doc and create a PR to merge the changes back into the repo. This mode is known as the suggest action.

Using the Workflows

Generation Workflow

The .github/workflows/sdk-generation.yaml workflow provides a reusable workflow for generating SDKs.

When you use the action in direct mode, the generation workflow will generate SDKs and publish them to package managers. If you use the action in pr mode, the generation workflow will generate SDKs and create a PR to merge the changes back into the main repo.

If you generate SDKs in pr mode, you can use the .github/workflows/sdk-publish.yaml workflow to publish them to package managers when the PR is merged into the main branch.

The generation workflow also validates the provided OpenAPI document and gives you warnings and errors in the workflow output that you can address.

Here is an example configuration of a generation workflow using the pr mode of the action:


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

Publishing Workflow

If you generate an SDK in pr mode, you can use the .github/workflows/sdk-publish.yaml workflow to publish it to package managers when the PR is merged into the main branch. The publishing workflow also creates a GitHub release for the new SDK version.

Here is an example configuration of a publishing workflow using the pr mode of the action:


name: Publish
on:
on:
push: # Will trigger when the RELEASES.md file is updated by the merged PR from the generation workflow
paths:
- 'RELEASES.md'
branches:
- main
jobs:
publish:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-publish.yaml@v14 # Import the SDK publishing workflow to handle publishing to the package managers
with:
publish_python: true # Tells the publishing action to publish the Python SDK to PyPI
create_release: true
secrets:
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

Validation Workflow

You can use the .github/workflows/sdk-generation.yaml workflow to validate an OpenAPI document by running the validate action.

Here is an example configuration of a workflow using the validate action:


name: Validate
on:
workflow_dispatch: {} # Allows manual triggering of the workflow to validate the OpenAPI doc
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
validate:
uses: speakeasy-api/sdk-generation-action@v14 # Use the action directly to handle the validation of the OpenAPI doc
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}

Suggestion Workflow

The .github/workflows/sdk-suggestion.yaml workflow provides a reusable workflow for applying suggestions to provided OpenAPI docs. Use this workflow to create a PR to merge the changes containing the applied suggestions back into the repo.

Below is example configuration of a workflow using the suggest action:


name: Suggest
on:
workflow_dispatch: {} # Allows manual triggering of the workflow to suggest OpenAPI document
jobs:
suggest:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-suggestion.yaml@v14 # Import the sdk suggestion workflow which will handle applying suggestions to the OpenAPI document and creating a resulting PR.
with:
speakeasy_version: latest
openapi_docs: |
- ./openapi.yaml
openapi_doc_output: ./openapi.yaml
max_suggestions: 5
secrets:
github_access_token: ${{ secrets.GITHUB_TOKEN }}
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
openai_api_key: ${{ secrets.OPENAI_API_KEY }}

Generation Workflow

The .github/workflows/sdk-generation.yaml workflow provides a reusable workflow for generating SDKs.

When you use the action in direct mode, the generation workflow will generate SDKs and publish them to package managers. If you use the action in pr mode, the generation workflow will generate SDKs and create a PR to merge the changes back into the main repo.

If you generate SDKs in pr mode, you can use the .github/workflows/sdk-publish.yaml workflow to publish them to package managers when the PR is merged into the main branch.

The generation workflow also validates the provided OpenAPI document and gives you warnings and errors in the workflow output that you can address.

Here is an example configuration of a generation workflow using the pr mode of the action:

Publishing Workflow

If you generate an SDK in pr mode, you can use the .github/workflows/sdk-publish.yaml workflow to publish it to package managers when the PR is merged into the main branch. The publishing workflow also creates a GitHub release for the new SDK version.

Here is an example configuration of a publishing workflow using the pr mode of the action:

Validation Workflow

You can use the .github/workflows/sdk-generation.yaml workflow to validate an OpenAPI document by running the validate action.

Here is an example configuration of a workflow using the validate action:

Suggestion Workflow

The .github/workflows/sdk-suggestion.yaml workflow provides a reusable workflow for applying suggestions to provided OpenAPI docs. Use this workflow to create a PR to merge the changes containing the applied suggestions back into the repo.

Below is example configuration of a workflow using the suggest action:


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

Generation

Direct Mode

In direct mode, the generation action does the following:

  • Downloads the latest or pinned version of the Speakeasy CLI.
  • Clones the associated repo.
  • Downloads or loads the latest OpenAPI doc from a URL or the repo.
  • Validates the OpenAPI doc.
  • Checks for changes to the OpenAPI doc and the Speakeasy CLI version.
  • Generates a new SDK for the configured languages, if necessary.
  • Creates a commit with the new SDK (or SDKs) and pushes it to the repo.
  • Optionally creates a GitHub release for the new commit.

PR Mode

In PR mode, the generation action does the following:

  • Downloads the latest or pinned version of the Speakeasy CLI.
  • Clones the associated repo.
  • Creates a branch or updates an existing branch for the new SDK version.
  • Downloads or loads the latest OpenAPI doc from a URL or the repo.
  • Validates the OpenAPI doc.
  • Checks for changes to the OpenAPI doc and the Speakeasy CLI version.
  • Generates a new SDK for the configured languages, if necessary.
  • Creates a commit with the new SDK (or SDKs) and pushes it to the repo.
  • Creates a PR from the new branch to the main branch or updates an existing PR.

Inputs

speakeasy_api_key

Required The Speakeasy API key to use to authenticate the CLI run by the action. Create a new API key in the Speakeasy Platform (opens in a new tab).


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

openai_api_key

The OpenAI API key used to authenticate GPT requests issued by the suggest action. Create a new API key in the OpenAI Platform (opens in a new tab). If no OpenAI API key is provided, the Speakeasy OpenAI API key will be used.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

action

The action to run. Valid options are validate, generate, finalize, suggest, finalize-suggest, or release. Defaults to generate.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

mode

The mode to run the action in. Valid options are direct or pr. Defaults to direct.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

  • Running the action in direct mode will create a commit with the changes to the SDKs and push them directly to the branch the workflow is configured to run on (normally main or master). If create_release is true, the action will create a GitHub release for the new commit immediately after the commit is created on the branch.
  • Running the action in pr mode will create a new branch to commit the changes to the SDKs to and then create a PR from this new branch. You can configure the publishing workflow to run when the PR is merged to publish the SDKs and create a release.

speakeasy_version

The version of the Speakeasy CLI to use or "latest". Defaults to "latest".


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

openapi_docs

Required A YAML string containing a list of OpenAPI documents to use. If multiple documents are listed, they will be merged before generating the SDKs.

If the document lives within the repo, you can use a relative path. If the document is hosted publicly, you can provide the URL.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

If the documents are hosted privately, you can provide the URL along with the openapi_doc_auth_header and openapi_doc_auth_token inputs. Each document will be fetched using the provided auth header and token, so they need to be valid for all documents.

openapi_doc_location

Required The location of the OpenAPI document to use, either a relative path within the repo or a URL to a publicly hosted document.

openapi_doc_auth_header

The auth header to use when fetching the OpenAPI document if it is not publicly hosted, for example, Authorization. If the OpenAPI document is hosted in a private github repository owned by your team or company then use Authorization. If the OpenAPI document is a private Speakeasy-hosted document, use x-api-key. This header will be populated with the openapi_doc_auth_token provided.

openapi_doc_auth_token

The auth token to use when fetching the OpenAPI document if it is not publicly hosted, for example, Bearer <token> or <token>. If your schema is hosted in a private github repository owned by your team or company then openapi_doc_auth_token is a Personal Access Token (opens in a new tab) prefixed with the string token .

openapi_doc_output

The output path of the modified OpenAPI spec when running the suggest action. Defaults to ./openapi.yaml.


name: Suggest
on:
workflow_dispatch: {} # Allows manual triggering of the workflow to suggest OpenAPI document
jobs:
suggest:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-suggestion.yaml@v14 # Import the sdk suggestion workflow which will handle applying suggestions to the OpenAPI document and creating a resulting PR.
with:
speakeasy_version: latest
openapi_docs: |
- ./openapi.yaml
openapi_doc_output: ./openapi.yaml
max_suggestions: 5
secrets:
github_access_token: ${{ secrets.GITHUB_TOKEN }}
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
openai_api_key: ${{ secrets.OPENAI_API_KEY }}

overlay_docs

Define one or more overlays to apply to your openapi document before generation. Please see the overlay documentation for more information.


```yaml focus=20:21
name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
overlay_docs: |
- location: ./overlay.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
working-directory: app
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}
---
### `max_suggestions`
The maximum number of suggestions to apply when running the `suggest` action. Defaults to `5`.
```yaml focus=14
name: Suggest
on:
workflow_dispatch: {} # Allows manual triggering of the workflow to suggest OpenAPI document
jobs:
suggest:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-suggestion.yaml@v14 # Import the sdk suggestion workflow which will handle applying suggestions to the OpenAPI document and creating a resulting PR.
with:
speakeasy_version: latest
openapi_docs: |
- ./openapi.yaml
openapi_doc_output: ./openapi.yaml
max_suggestions: 5
secrets:
github_access_token: ${{ secrets.GITHUB_TOKEN }}
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
openai_api_key: ${{ secrets.OPENAI_API_KEY }}

github_access_token

Required A GitHub access token with write access to the repo.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

languages

Required A YAML string containing a list of languages to generate SDKs for, for example:


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- go # Using the default output of ./go-client-sdk
- python # Using the default output of ./python-client-sdk
- typescript # Using the default output of ./typescript-client-sdk
- java # Using the default output of ./java-client-sdk
- php # Using the default output of ./php-client-sdk
- ruby # Using the default output of ./ruby-client-sdk
- terraform # Single-language repo only
- docs # configuration to render the sdk docs target
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

If multiple languages are listed, Speakeasy will treat the repo as a monorepo. If a single language is listed, Speakeasy will treat the repo as a single-language repo.

docs_languages

A YAML string containing a list of language targets to generate SDK docs for. This should only be used if the language target is set to docs.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- docs
docs_languages: |-
- go
- python
- typescript
- java
- csharp
- unity
- curl
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

create_release

Whether to create a release for the new SDK version if using direct mode. Defaults to "true". This will also create a tag for the release, allowing the Go SDK to be retrieved via a tag with Go modules.


name: Publish
on:
on:
push: # Will trigger when the RELEASES.md file is updated by the merged PR from the generation workflow
paths:
- 'RELEASES.md'
branches:
- main
jobs:
publish:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-publish.yaml@v14 # Import the SDK publishing workflow to handle publishing to the package managers
with:
publish_python: true # Tells the publishing action to publish the Python SDK to PyPI
create_release: true
secrets:
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

publish_python

(Workflow Only) Whether to publish the Python SDK to PyPI. Defaults to "false".

Note: In pr mode, you need to set this in the generation and publishing workflows.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

publish_typescript

(Workflow Only) Whether to publish the TypeScript SDK to npm. Defaults to "false".

Note: In pr mode, you need to set this in the generation and publishing workflows.

publish_terraform

(Workflow Only) Whether to publish the Terraform provider to the Terraform Registry. Defaults to "false".

publish_java

(Workflow Only) Whether to publish the Java SDK to the OSSRH URL configured in gen.yaml. Defaults to "false".

publish_php

(Workflow Only) Whether to publish the PHP SDK for Composer. Defaults to "false".

Note: In pr mode, you need to set this in the generation and publishing workflows.

publish_ruby

(Workflow Only) Whether to publish the Ruby SDK to RubyGems. Defaults to "false".

Note: In pr mode, you need to set this in the generation and publishing workflows.

working_directory

The working directory to use when running Speakeasy CLI commands in the action. If this input is not specified, the root of the repo will be used.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
working-directory: app
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

speakeasy_api_key

Required The Speakeasy API key to use to authenticate the CLI run by the action. Create a new API key in the Speakeasy Platform (opens in a new tab).

openai_api_key

The OpenAI API key used to authenticate GPT requests issued by the suggest action. Create a new API key in the OpenAI Platform (opens in a new tab). If no OpenAI API key is provided, the Speakeasy OpenAI API key will be used.

action

The action to run. Valid options are validate, generate, finalize, suggest, finalize-suggest, or release. Defaults to generate.

mode

The mode to run the action in. Valid options are direct or pr. Defaults to direct.

  • Running the action in direct mode will create a commit with the changes to the SDKs and push them directly to the branch the workflow is configured to run on (normally main or master). If create_release is true, the action will create a GitHub release for the new commit immediately after the commit is created on the branch.
  • Running the action in pr mode will create a new branch to commit the changes to the SDKs to and then create a PR from this new branch. You can configure the publishing workflow to run when the PR is merged to publish the SDKs and create a release.

speakeasy_version

The version of the Speakeasy CLI to use or "latest". Defaults to "latest".

openapi_docs

Required A YAML string containing a list of OpenAPI documents to use. If multiple documents are listed, they will be merged before generating the SDKs.

If the document lives within the repo, you can use a relative path. If the document is hosted publicly, you can provide the URL.

If the documents are hosted privately, you can provide the URL along with the openapi_doc_auth_header and openapi_doc_auth_token inputs. Each document will be fetched using the provided auth header and token, so they need to be valid for all documents.

openapi_doc_location

Required The location of the OpenAPI document to use, either a relative path within the repo or a URL to a publicly hosted document.

openapi_doc_auth_header

The auth header to use when fetching the OpenAPI document if it is not publicly hosted, for example, Authorization. If the OpenAPI document is hosted in a private github repository owned by your team or company then use Authorization. If the OpenAPI document is a private Speakeasy-hosted document, use x-api-key. This header will be populated with the openapi_doc_auth_token provided.

openapi_doc_auth_token

The auth token to use when fetching the OpenAPI document if it is not publicly hosted, for example, Bearer <token> or <token>. If your schema is hosted in a private github repository owned by your team or company then openapi_doc_auth_token is a Personal Access Token (opens in a new tab) prefixed with the string token .

openapi_doc_output

The output path of the modified OpenAPI spec when running the suggest action. Defaults to ./openapi.yaml.

overlay_docs

Define one or more overlays to apply to your openapi document before generation. Please see the overlay documentation for more information.

github_access_token

Required A GitHub access token with write access to the repo.

languages

Required A YAML string containing a list of languages to generate SDKs for, for example:

If multiple languages are listed, Speakeasy will treat the repo as a monorepo. If a single language is listed, Speakeasy will treat the repo as a single-language repo.

docs_languages

A YAML string containing a list of language targets to generate SDK docs for. This should only be used if the language target is set to docs.

create_release

Whether to create a release for the new SDK version if using direct mode. Defaults to "true". This will also create a tag for the release, allowing the Go SDK to be retrieved via a tag with Go modules.

publish_python

(Workflow Only) Whether to publish the Python SDK to PyPI. Defaults to "false".

Note: In pr mode, you need to set this in the generation and publishing workflows.

publish_typescript

(Workflow Only) Whether to publish the TypeScript SDK to npm. Defaults to "false".

Note: In pr mode, you need to set this in the generation and publishing workflows.

publish_terraform

(Workflow Only) Whether to publish the Terraform provider to the Terraform Registry. Defaults to "false".

publish_java

(Workflow Only) Whether to publish the Java SDK to the OSSRH URL configured in gen.yaml. Defaults to "false".

publish_php

(Workflow Only) Whether to publish the PHP SDK for Composer. Defaults to "false".

Note: In pr mode, you need to set this in the generation and publishing workflows.

publish_ruby

(Workflow Only) Whether to publish the Ruby SDK to RubyGems. Defaults to "false".

Note: In pr mode, you need to set this in the generation and publishing workflows.

working_directory

The working directory to use when running Speakeasy CLI commands in the action. If this input is not specified, the root of the repo will be used.


name: Generate
on:
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
inputs:
force:
description: "Force generation of SDKs"
type: boolean
default: false
schedule:
- cron: 0 0 * * * # Runs every day at midnight
jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14 # Import the SDK generation workflow to handle the generation of the SDKs and publishing to the package managers in direct mode
with:
speakeasy_version: latest
openapi_docs: |
- location: https://www.speakeasyapi.dev/openapi.yaml
languages: |-
- python
publish_python: true # Tells the generation action to generate artifacts for publishing to PyPI
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
pypi_token: ${{ secrets.PYPI_TOKEN }}

Outputs

python_regenerated

This will be true if the Python SDK was regenerated.

python_directory

The directory the Python SDK was generated in.

typescript_regenerated

This will be true if the Typescript SDK was regenerated.

typescript_directory

The directory the Typescript SDK was generated in.

go_regenerated

This will be true if the Go SDK was regenerated.

go_directory

The directory the Go SDK was generated in.

java_regenerated

This will be true if the Java SDK was regenerated.

java_directory

The directory the Java SDK was generated in.

php_regenerated

This will be true if the PHP SDK was regenerated.

php_directory

The directory the PHP SDK was generated in.

terraform_regenerated

This will be true if the Terraform provider was regenerated.

terraform_directory

The directory the Terraform provider was generated in.

ruby_regenerated

This will be true if the Ruby SDK was regenerated.

ruby_directory

The directory the Ruby SDK was generated in.

cli_output

The output of the Speakeasy CLI command used in the suggest action.

Publishing

You can use the reusable workflows included to publish the SDKs to package managers.

Java (Maven -- Sonatype Central Portal)

This section covers how to publish to Sonatype's central portal. For legacy OSSRH publishing support, see the next section.

In order to publish, you must do the following:

  • If you've never published to Maven before, you must set up a Sonatype Central Portal account. Follow the instructions here (opens in a new tab) to do so.
  • You will need a Sonatype-generated username and password for authentication. Click your username in the top right -> view account -> generate user token.
    • Store the username and password as GitHub secrets
  • Create a Sonatype namespace. Follow the instructions here (opens in a new tab).
  • You will need a GPG key to sign the artifacts. Follow the instructions here (opens in a new tab) to create one. An abbreviated guide is provided below.
    • Install gnupg on your machine (e.g. brew install gnupg)
    • Run gpg --gen-key. Note the keyId (e.g. CA925CD6C9E8D064FF05B4728190C4130ABA0F98) and shortId (last 8 characters of the keyId, e.g. 0ABA0F98).
    • Run gpg --keyserver keys.openpgp.org --send-keys <your_keyId>
    • Run gpg --export-secret-keys --armor <your_shortId> > secret_key.asc
    • secret_key.asc will contain your GPG secret key
  • Add your GPG secret key and passphrase as GitHub secrets
  • Populate the secrets section of the workflow file with your secrets. Modify the values of secrets.<MY_SECRET_NAME> as needed in the following example:
    • ossrh_username: ${{ secrets.OSSRH_USERNAME }}
    • ossrh_password: ${{ secrets.OSSRH_PASSWORD }}
    • java_gpg_secret_key: ${{ secrets.GPG_SECRET_KEY }}
    • java_gpg_passphrase: ${{ secrets.GPG_PASSPHRASE }}
  • In the workflow file, set the following:
    • publish_java: true
    • use_sonatype_central: true
  • In the java section of gen.yaml, ensure the groupId you've provided matches your OSSRH org and the artifact name you want. For example:
    • groupID: com.example
    • artifactID: example-sdk
  • In the java section of gen.yaml, provide the additional configuration required for publishing to Maven. Do not supply an ossrh_url. The below fields are required:
    • githubURL: github.com/org/repo
    • companyName: My Company
    • companyURL: https://www.mycompany.com
    • companyEmail: info@mycompany.com

Java (Maven -- Sonatype legacy OSSRH)

Java SDKs generated by the Speakeasy Generation Action are published to a Sonatype Open Source Software Repository Hosting (OSSRH) staging repository.

To publish your Java SDKs to OSSRH, you need to do the following:

  • If you've never published to Maven before, set up an OSSRH staging repository by following the instructions in this getting started guide (opens in a new tab).
  • You will need a GPG key to sign the artifacts. Follow the instructions in this GPG guide (opens in a new tab) to create one. What follows is an abbreviated guide to creating a GPG key.
    • Install GnuPG on your machine (for example, using brew install gnupg).
    • Run gpg --gen-key. Note the keyId (for example, CA925CD6C9E8D064FF05B4728190C4130ABA0F98) and shortId (the last 8 characters of the keyId, for example, 0ABA0F98).
    • Run gpg --keyserver keys.openpgp.org --send-keys <your_keyId>.
    • Run gpg --export-secret-keys --armor <your_shortId> > secret_key.asc.
    • secret_key.asc will contain your GPG secret key.
  • Add your GPG secret key and passphrase as GitHub secrets.
  • Add your OSSRH username and password as GitHub secrets.
  • Populate the secrets section of the workflow file with your secrets. For example:
    • ossrh_username: ${{ secrets.OSSRH_USERNAME }}
    • ossrh_password: ${{ secrets.OSSRH_PASSWORD }}
    • java_gpg_secret_key: ${{ secrets.JAVA_GPG_SECRET_KEY }}
    • java_gpg_passphrase: ${{ secrets.JAVA_GPG_PASSPHRASE }}
  • In the workflow file, set publish_java: true.
  • In the java section of gen.yaml, ensure the groupId you've provided matches your OSSRH org and the artifact name you want. For example:
    • groupID: com.example
    • artifactID: example-sdk
  • In the java section of gen.yaml, provide the additional configuration required for publishing to Maven. The below fields are required:
    • ossrhURL: https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/
    • githubURL: github.com/org/repo
    • companyName: My Company
    • companyURL: https://www.mycompany.com
    • companyEmail: info@mycompany.com

C# (NuGet)

C# SDKs generated by Speakeasy are published to NuGet.

To publish your C# SDKs to NuGet, you need to do the following:

  • Create a NuGet (opens in a new tab) account.
  • You will need a NuGet API key to publish to NuGet. When creating your NuGet API key:
    • Set the Package Owner field to the user or organization that will "own" your SDK artifact.
    • Ensure that the API key has the relevant Push scoped (if the package already exists, the API key may not need "Push new packages and package versions" permissions).
    • Populate the Glob Pattern and Available Packages fields in a way that will permit publishing your SDK (use the packageName specified in gen.yaml).
  • Set a GitHub Actions secret named NUGET_API_KEY with your API key as its value.
  • Populate the secrets section of the workflow with nuget_api_key: ${{ secrets.NUGET_API_KEY }}.
  • In the generation.yaml file, add publish_csharp: true to the with section.
  • If you're generating SDKs in pr mode, add publish_csharp: true to the with section of the publish.yaml file.

Terraform Registry

You can configure the Speakeasy Generation Action to publish a generated Terraform provider. Note that Speakeasy Terraform provider generation does not support operating in monorepo mode, as you need to create a separate repository for the Terraform provider.

To publish the generated Terraform provider, you need to do the following:

  • The repository you make for the Terraform provider must:
    • Be given the name terraform-provider-{NAME}, where NAME is lowercase.
    • Be public.
  • You will need to sign your Terraform provider releases with a signing key. Create and export a signing key following the instructions in the GitHub documentation for generating a new GPG key (opens in a new tab). Generate your GPG key using either the RSA or DSA algorithm.
  • Take note of the following values:
    • The GPG private key
    • The GPG passphrase
    • The GPG public key
  • Add the ASCII-armored public key to the Terraform registry.
  • Your GPG private key and GPG passphrase will be configured automatically if they are entered into the Speakeasy CLI. Ensure that the following secrets are available to your repository:
    • The GPG private key TERRAFORM_GPG_PRIVATE_KEY
    • The GPG passphrase TERRAFORM_GPG_PASSPHRASE
  • The first time you publish a Terraform provider generated using the Speakeasy Generation Action, you will need to manually add it to the Terraform Registry. Subsequent updates will be published automatically. To begin this process, follow the Terraform registry instructions (opens in a new tab) and agree to any Terraform terms and conditions. Note that you will need to be an organizational admin to complete this step.

Validation

The validation action does the following:

  • Downloads the latest or pinned version of the Speakeasy CLI.
  • Clones the associated repo.
  • Downloads or loads the latest OpenAPI doc from a URL or the repo.
  • Validates the OpenAPI doc using the Speakeasy CLI Validation Tool.
  • Returns a success or failure message based on detected warnings and errors.

Suggestion

The suggestion action does the following:

  • Downloads the latest or pinned version of the Speakeasy CLI.
  • Clones the associated repo.
  • Downloads or loads the latest OpenAPI doc from a URL or the repo.
  • Generates suggestions for the OpenAPI doc, applies them, and outputs to a local filepath using the Speakeasy CLI.
  • Creates a PR with this modified document.
  • Adds PR comments containing the validation error for that line number, the suggested fix for that error, and an explanation of the fix.