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://docs.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://docs.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 the provided OpenAPI doc(s). This workflow can be used 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

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.

Publishing

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

Java (Maven)

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.

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).

`openai_api_key`

The OpenAI API Key to use to authenticate GPT requests issued by the suggest action. Create a new API Key in the OpenAI Platform (opens in a new tab). If not provided, Speakeasy's 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.

Example:

openapi_docs: |
  - https://example.com/openapi1.json
  - https://example.com/openapi2.json

`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 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>.

`openapi_doc_output`

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

`max_suggestions`

The maximum number of suggestions to apply when running the suggest action. Defaults to 5.

`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:

languages: |
  - go: ./go-sdk # Specifying the output directory
  - 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

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.

`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.

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.