The sdk-generation-action provides both an action and workflows to generate Client SDKs from an OpenAPI document using the Speakeasy CLI tool. You can use these to manage CI/CD (ie the automatic generation and publishing of Client SDKs) in a repo containing the generated SDKs.

You can find more information about our Client SDK Generator for OpenAPI Documents here: https://docs.speakeasyapi.dev/docs/using-speakeasy/client-sdks/index.html

The included workflows provides option for publishing the SDKs to various package managers once the action is successful, either via PR or directly to the repo.

This action provides a self contained solution for automatically generating new versions of a client SDK when either the reference OpenAPI doc is updated or the Speakeasy CLI that is used to generate the SDKs is updated.

The action can be used in two ways:

• Configured to generate and commit directly to a branch in the repo (such as main or master). This mode is known as direct mode.
• Configured to generate and commit to a auto-generated branch, then create a PR to merge the changes back into the main repo. This mode is known as pr mode.

The action runs through the following steps:

• 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
• 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(s) and pushes it to the repo
• Optionally creates a Github release for the new commit

The action runs through the following steps:

• 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
• 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(s) and pushes it to the repo
• Creates a PR from the new branch to the main branch or updates an existing PR

Publishing is provided by using the included reusable workflows. These workflows can be used to publish the SDKs to various package managers. See below for more information.

Required The Speakeasy API Key to use to authenticate the CLI run by the action. Create a new API Key in the Speakeasy Platform.

The mode to run the action in, valid options are direct or pr, defaults to direct.

• direct will create a commit with the changes to the SDKs and push them directly to the branch the workflow is configure to run on (normally 'main' or 'master'). If create_release is true this will happen immediately after the commit is created on the branch.
• pr will instead create a new branch to commit the changes to the SDKs to and then create a PR from this branch. The sdk-publish workflow will then need to be configured to run when the PR is merged to publish the SDKs and create a release.

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

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

The auth header to use when fetching the OpenAPI document if it is not publicly hosted. For example Authorization. If using a private speakeasy hosted document use x-api-key. This header will be populated with the openapi_doc_auth_token provided.

The auth token to use when fetching the OpenAPI document if it is not publicly hosted. For example Bearer <token> or <token>.

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

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

languages: |
  - go: ./go-sdk # specifying a output directory
  - python # using default output of ./python-client-sdk
  - typescript # using default output of ./typescript-client-sdk
  - java # using default output of ./java-client-sdk
  - php # using default output of ./php-client-sdk

If multiple languages are present we will treat the repo as a mono repo, if a single language is present as a single language repo.

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

(Workflow Only) Whether to publish the Python SDK to PyPi. Default "false".

(Workflow Only) Whether to publish the TypeScript SDK to NPM. Default "false".

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

true if the Python SDK was regenerated

The directory the Python SDK was generated in

true if the Typescript SDK was regenerated

The directory the Typescript SDK was generated in

true if the Go SDK was regenerated

The directory the Go SDK was generated in

true if the Java SDK was regenerated

The directory the Java SDK was generated in

true if the PHP SDK was regenerated

The directory the PHP SDK was generated in

If just using the action on its own (without the workflow publishing) you can use the action as follows:

name: Generate

on:
  workflow_dispatch: {} # Allows manual triggering of the workflow to generate SDK
  schedule:
    - cron: 0 0 * * * # Runs every day at midnight

jobs:
  generate:
    name: Generate SDK
    runs-on: ubuntu-latest
    steps:
      - uses: speakeasy-api/sdk-generation-action@v9
        with:
          speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
          speakeasy_version: latest
          openapi_doc_location: https://docs.speakeasyapi.dev/openapi.yaml
          github_access_token: ${{ secrets.GITHUB_TOKEN }}
          languages: |-
            - go

The .github/workflows/speakeasy_sdk_generation.yml workflow provides a reusable workflow for generating the SDKs. This workflow can be used to generate the SDKs and publish them to various package managers if using the direct mode of the action or to generate the SDKs and create a PR to merge the changes back into the main repo if using the pr mode of the action. If using pr mode you can then use the .github/workflows/speakeasy_sdk_publish.yml workflow to publish the SDKs to various package managers on merge into the main branch.

Below is example configuration of a workflow using the pr mode of the action:

name: Generate

on:
  workflow_dispatch: {} # Allows manual triggering of the workflow to generate SDK
  schedule:
    - cron: 0 0 * * * # Runs every day at midnight

jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v9 # Import the sdk generation workflow which will handle the generation of the SDKs and publishing to the package managers in 'direct' mode.
    with:
      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
      speakeasy_version: latest
      openapi_doc_location: https://docs.speakeasyapi.dev/openapi.yaml
      languages: |-
        - python
      publish_python: true
      mode: pr
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      pypi_token: ${{ secrets.PYPI_TOKEN }}

When using the action or workflow in pr mode you can use the .github/workflows/speakeasy_sdk_publish.yml workflow to publish the SDKs to various package managers on merge into the main branch, and create a Github release for the new SDK version.

Below is example configuration of a 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@v9 # Import the sdk publish workflow which will handle the publishing to the package managers
    with:
      publish_python: true
      create_release: true
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      pypi_token: ${{ secrets.PYPI_TOKEN }}