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

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, create a new GitHub action by clicking Actions > New workflow > set up a workflow yourself ->

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

Example:

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

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.

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:

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:

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

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.