Automate SDK Gen with Github Actions

The worst part of making changes to an API is propogating 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. In this tutorial we'll show you how you can automate away this headache by using GitHub Actions and the Speakeasy CLI to easily automate the creation and ongoing updates of your client SDKs whenever there are changes to your OpenAPI schema.

What are Github Actions?

They are “a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline.” What makes, GitHub Actions especially useful is that they live in the same place as your code. This makes it easy to trigger based on updates to the code in your repository. Events such as opening a pull request, creating a branch, or updating an OpenAPI schema can trigger a workflow.

Set up SDK Repo and Provision Access

Create Repo

info

If you don't have your own OpenAPI schema available, you can fork our template repo which has an openapi folder holding a spec: openapi.yaml.

If you are using your own OpenAPI spec, go ahead and create a new repo to hold the client SDKs that we are going to auto-generate. Give it a name like, speakeasy-sdk-tutorial and a description, then click Create repository:

Clone into the repo and then create an openapi subdirectory and add your OpenAPI spec to the subdirectory.

Using the Speakeasy CLI in your Github Action

Create a New Workflow

In the repo that holds your OpenAPI file go ahead and create a new Github action by clicking Actions > New workflow > set up a workflow yourself ->

Name the action generate-sdks, copy and paste the following code snippet into the body, and save the file (we'll walk through the details of the action in the next section):

name: Generate

on:
  push:
    branches:
      - main
    paths:
      - openapi/**

jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v3.6 # Import the sdk generation workflow which will handle the generation of the SDKs and publishing to the package managers
    with:
      speakeasy_version: latest
      openapi_doc_location: /openapi/openapi.yaml
      languages: |
        - python: ./sdks/python
        - typescript: ./sdks/ts
        - go: ./sdks/go
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}

Action Explained

The Trigger

on:
  push:
    branches:
      - main
    paths:
      - openapi/**

The trigger specifies that the Generate action will be performed when an update is pushed to the openapi folder of the repo.

The Generate Step

generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v3.6

The workflow we created is in turn calling another workflow that the Speakeasy team has created. The action maintained by the Speakeasy team, spisn up a docker container, runs the Speakeasy CLI and generates SDKs using the provided arguments.

The Arguments

with:
    speakeasy_version: latest
    openapi_doc_location: /openapi/openapi.yaml
    languages: |
    - python: ./sdks/python
    - typescript: ./sdks/ts
    - go: ./sdks/go
secrets:
    github_access_token: ${{ secrets.GITHUB_TOKEN }}

The Speakeasy action needs to know a few things before it can run. It needs to know what version of the CLI it should use to create the SDKs: speakeasy_version. It needs to know where it can find the openAPI spec which will be used for the gneeration: openapi_doc_location. It needs to know what languages the SDKs should be generated in, and where the SDKs should be outputed.- python: ./sdks/python tells the action to generate a python SDK and put it in a subdirectory, sdks/python/, of the repository with the OpenAPI. Finally, you need to give the Speakeasy action an access token to write to the respository. Fortunately Github has a dedicated secret which for actions which handles this: ${{ secrets.GITHUB_TOKEN }}.

Run the Action

To trigger the action to run, let's simulate a change to the OpenAPI schema. In this case, we won't really change the contents, but go ahead and bump the version number at the top of the openapi.yaml file (line 5) from 0.1.0 to 0.2.0.

When the change is pushed to github, the action should begin to run. Ater a minute or so, you should see in the repository that a new subdirectory has been created which holds the 3 autogenerated sdks:

What's Next

In this tutorial, we used the Speakeasy github action to automate the generation of our SDKs to make sure they stay in sync with our OpenAPI schema, but in a production use case, you will also need to make sure new SDKs are published to the relevatn package managers. Fortunately, the Speakeasy action makes this easy. Head over to the full action docs to see how you can automate package publishing.