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.
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.
For information on publishing, see here.
5. GitHub Actions Workflow Permissions
If you see a 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:
Configure Remote URLs for Schemas
Warning
Remote URLs for your OpenAPI schema must be stable. Speakeasy does not support dynamically constructed URLs in workflow files.
If your OpenAPI schema is hosted in a different repository or at a remote URL, set the source as the remote URL in .speakeasy/workflow.yaml. Run speakeasy configure sources and follow the prompts to add the remote URL.
To authenticate the remote URL, provide a token or key, preferably stored as an environment variable (e.g., $OPENAPI_DOC_TOKEN) to avoid exposure or accidental inclusion in GitHub.
Add a GitHub Secret (opens in a new tab) with the same name and value as your token/key for authentication.