Create Your SDK On GitHub

Success Icon


We recommend that you use our managed SDK pipeline to set up your SDKs. However, if you want to use the GitHub workflow directly, you can follow the steps below.

The worst part of making changes to an API is propagating those changes downstream to all your API artifacts. If you support your API with client SDKs, any changes to your API may mean making changes to a dozen SDKs.

However, by integrating the Speakeasy GitHub workflow into your CI/CD, you can easily automate the creation and ongoing updates of your client SDKs whenever there are changes to your OpenAPI schema.

Set Up Your SDK Repo

Create a new repo to hold the client SDKs that we are going to autogenerate. We recommend that you create one repo for each (language) SDK. Alternatively, you can make a monorepo to hold every language (see the SDK creation documentation for more details on this choice). Give it a name, like api-name-language-sdk, and a description, then click Create repository.

Add a Config File to the Root of Your Repo

Create a file named gen.yaml. This will contain a set of additional configurations that the SDK creation workflow will use to create the package you want, with the code style you prefer.

See below for per-language examples of the gen.yaml file, which you can copy and edit:

telemetryEnabled: false
sdkClassName: api-name
singleTagPerOp: false
maxMethodParams: 4
version: 0.1.0

Create the Generation Action

In your SDK repo, create a new GitHub action by clicking Actions > New workflow > set up a workflow yourself ->

How to create a new action in the GitHub UI

Name the action speakeasy_sdk_generation.yml. Copy and paste the following code snippet into the body for the language of your choice, and save the file (we'll walk through the details of the action in the next section):

name: Generate
workflow_dispatch: # Allows manual triggering of the workflow to generate SDK
description: "Force generation of SDKs"
type: boolean
default: false
- cron: 0 0 * * * # Runs every day at midnight
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14
speakeasy_version: latest
openapi_docs: |
- [OpenAPI Location]
languages: |
- go
create_release: true
force: ${{ github.event.inputs.force }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

The workflow leverages a Speakeasy workflow (opens in a new tab). The action maintained by the Speakeasy team spins up a Docker container, runs the Speakeasy CLI, and generates SDKs using the provided arguments.

Link Your OpenAPI Specs

In the above code snippets, openapi_docs is an array with a single value [TO BE FILLED IN]. The Generation workflow can support an arbitrary number of OpenAPI specs. If you specify multiple specs, they will be merged into a single package.

Our recommendation is to host your spec (or specs) at a stable and publicly available URL. However, if you don't have a public URL, you can also host the spec at a private URL or in a subdirectory of your SDK repo.


openapi_docs: |

openapi_docs: |
- ./openapi/openapi.yaml

Privately Hosted Specs

If your spec is privately hosted, you will need to add additional inputs to the workflow:

  • openapi_doc_auth_header: The auth header to use when fetching the OpenAPI spec. For example:

openapi_doc_auth_header: Authorization`

  • openapi_doc_auth_token: The auth token to use when fetching the OpenAPI spec, added as an additional repo secret. For example:

openapi_doc_auth_token: ${{ secrets.OPENAPI_AUTH_TOKEN }}

Add Repo Secrets

The generation workflow relies on some secrets, for example, ${{ secrets.SPEAKEASY_API_KEY }}, which need to be added to your repository for it to run successfully.

You can add these secrets by going to Settings > Secrets & Variables > Actions and clicking New repository secret.

The SPEAKEASY_API_KEY is always required as a secret in your SDK repository (find instructions for creating a Speakeasy API key below). The other secrets are required depending on the language of the SDK and which package manager you will publish to.

Create a Speakeasy API Key

To create a Speakeasy API key, head over to the Speakeasy dashboard (opens in a new tab) and click on the API Keys tab. Click Create API Key and give it a name, for example, SDK Creation.

Copy the key value and add it to your repository as a secret named SPEAKEASY_API_KEY.

Showing the Speakeasy API key as a GitHub secret

Publishing Credentials

How you create and add the publishing credentials depends on the language and package manager you are using. See the table below for the details of each package manager:

Package ManagerCredential CreationNotes
GitHub (Go)Repo Visibility (opens in a new tab)If your repo is private, you'll need to add the Speakeasy app (opens in a new tab).
PyPI (Python)API Tokens (opens in a new tab)
NPM (JS/TS)Access Tokens (opens in a new tab)Be sure to create an access token of typeAutomation.
Packagist (PHP)See publishing packages (opens in a new tab)If you are publishing your PHP SDK, it must be in a single repo (monorepo not permitted).

Enable PR Mode

The Speakeasy SDK Generation workflow can be run in two modes: PR and Push. The default mode is Push, which means that the workflow will automatically push new versions of the SDK to the repository. If you prefer the workflow to open PRs whenever a new version is ready, you can add mode: pr to the workflow file:

uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14
speakeasy_version: latest
openapi_doc_location: [TO BE FILLED IN]
languages: |-
- go
create_release: true
mode: pr
force: ${{ github.event.inputs.force }}
github_access_token: ${{ secrets.GITHUB_TOKEN }}
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

With PR mode enabled, you can manually review changes and make sure they are correct before merging them into the main branch.

To automatically receive notifications of new PRs that have been opened, add a CODEOWNERS file (opens in a new tab) to the SDK repo. You will automatically be added as a reviewer to any new PRs the workflow opens.

Run the Workflow and Create SDKs

Once you have added the workflow file to your repository, run the action by clicking the Actions tab in your repository, then the Generate workflow, and finally, the Run workflow button.

You will know the action worked if you see a green checkmark next to each workflow run, and it progresses all the way to the publishing step: Showing a successful workflow run

What's Next

You've now used the Speakeasy GitHub workflow to automate the creation and publishing of your SDKs to make sure they stay in sync with your OpenAPI schema. However, there are several optimizations you can add to your OpenAPI spec to ensure your SDKs are the best they can be. Check out our guide to customizing your SDK code.