Skip to main content

Create Your SDK On Github

tip

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 Speakeasy's 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

Go ahead and create a new repo to hold the client SDKs that we are going to auto-generate. We recommend that you create one repo for each (language) SDK. Alternatively, you can make a momnorepo to hold every language (see the SDK creation article 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:

generation:
telemetryEnabled: false
sdkClassName: api-name
singleTagPerOp: false
go:
maxMethodParams: 4
version: 0.1.0
packageName: github.com/org/repo-name

Create the Generation Action

In your SDK repo, go ahead and 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

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
with:
speakeasy_version: latest
openapi_docs: |
- [OpenAPI Location]
languages: |
- go
create_release: true
force: ${{ github.event.inputs.force }}
secrets:
github_access_token: ${{ secrets.GITHUB_TOKEN }}
speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

The workflow leverages a Speakeasy workflow. The action maintained by the Speakeasy team, spins up a docker container, runs the Speakeasy CLI and generates SDKs using the provided arguments.

In the above code snippets openapi_docs is an array with a single value [TO BE FILLED IN]. The Generation workflow is able to support an arbitratry number of OpenAPI specs. If you specify multiple specs, they will be merged together into a single package. Our recommendation is to host your spec(s) 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 even in a subdirectory of your SDK repo.

Example:

openapi_docs: |
- https://yourdomain.com/openapi-1.yaml
- https://yourdomain.com/openapi-2.yaml
openapi_docs: |
- ./openapi/openapi.yaml

Privately Hosted Specs

If you are using a privately-hosted spec, 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 a number of secrets i.e ${{ secrets.SPEAKEASY_API_KEY }} that need to be added to your repsoitory for it to run successfully.

You can add these secrets by going to Settings > Secrets & Variable > Actions and clicking New Repository Secret.

SPEAKEASY_API_KEY is always required as a secret in your SDK repository (we will walk through API creation below). The other secrets are required depending on the language of the SDK and which package manager you want to publish to.

Speakeasy API Key

To create a Speakeasy API key, head over to the Speakeasy dashboard and click on the API Keys tab. Click Create API Key and give it a name: SDK Creation.

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

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 each package manager's details:

Package ManagerCredential CreationNotes
Github (Go)Repo VisibilityIf your repo is private, you'll need to add the Speakeasy app.
PyPi (Python)API Tokens
NPM (JS/TS)Access TokensBe sure to create an access token of type: Automation.
Packagist (PHP)See publishing packagesIf 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. However, if you want the workflow to open PRs whenever a new version is ready, you simply add mode: pr to the workflow file:

jobs:
generate:
uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14
with:
speakeasy_version: latest
openapi_doc_location: [TO BE FILLED IN]
languages: |-
- go
create_release: true
mode: pr
force: ${{ github.event.inputs.force }}
secrets:
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, simply add a CODEOWNERS file to the SDK repo. This will automatically add you as a reviewer to any new PRs that are opened.

Run The Workflow & Create SDKs

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

You will know it 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 & publishing of your SDKs to make sure they stay in sync with your OpenAPI schema. However, there are a few more 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.