Create Your SDK on GitHub

Learn how to automate the creation and publishing of SDKs from your OpenAPI specifications using Speakeasy's GitHub workflows.

Prerequisites

  • A GitHub account and a repository for your SDKs.
  • Your API specification in OpenAPI format hosted publicly or in your GitHub repo.
  • The Speakeasy CLI installed on your machine.

Step-by-Step guide

1. Initialize SDK Repository

Create a new GitHub repository to host the autogenerated SDKs. We recommend a separate repo for each SDK for simplicity, but a monorepo is also supported.

2. Generate SDK Workflow Configuration

Run the Speakeasy CLI to configure your SDK generation workflow. This command initializes the configuration process, creating the necessary workflow files.


speakeasy configure github

After successfully running this command, you will see messages indicating the creation of .speakeasy/workflow.yaml and .github/workflows/sdk_generation.yaml. These files define your SDK generation workflow and the associated GitHub Action, respectively.

Screenshot of the terminal after successfully running Speakeasy configure Github.

3. Set Up GitHub Secrets

Configure the necessary GitHub secrets for authentication:

  • Navigate to Settings > Secrets & Variables > Actions in your GitHub repo. If you don't have access to this tab in the GitHub UI please reach out to your GitHub organizational owner to grant you repository ownership permissions (opens in a new tab).
  • Add a new secret named SPEAKEASY_API_KEY, obtainable from the link provided in your terminal.

4. Push to GitHub

Commit and push the generated workflow files to your GitHub repository.

Navigate to Actions in your GitHub repo to manually trigger the SDK generation workflow or wait for it to run automatically. You will know the action worked if you see a green checkmark next to each workflow run, and it progresses all the way through the generate step. The publishing step will be skipped if you haven't set up package publishing.

A screenshot of a successful generate flow.

For information on publishing, see here.

5. GitHub Actions Workflow Permissions

If you see an error message like 403 GitHub Actions is not permitted to create or approve pull requests. [] during generation, you need to update the GitHub actions permissions for your repository. Navigate to Settings > Actions > Workflow permissions in your GitHub repo and set the following permissions:

Github Actions workflow permissions.

Configure Remote URLs for Schemas

If your OpenAPI schema is hosted in a different repository or remote URL, configure the location of your source as a remote URL in the .speakeasy/workflow.yaml file. Run speakeasy configure sources and follow the prompts to add a remote URL to the source location.

Configure Remote URL for schema.

Next, if the schema is hosted at a remote URL, provide a token or key to authenticate the remote URL. It's recommended to store the key as an environment variable (for example, $OPENAPI_DOC_TOKEN) instead of hardcoding it in your workflow file to limit exposing the key or accidentally checking it into GitHub.

When setting up the repository on GitHub, make sure to add a GitHub Secret (opens in a new tab) with the same name and value as the token/key to authenticate your remote URL.

Warning Icon

WARN

If you use a remote URL for your OpenAPI schema, ensure the URL is stable. Speakeasy does not currently support dynamically constructed URLs in its workflow files.