SDK Generation Workflow

The SDK Generation workflow is powered by the Speakeasy CLI (opens in a new tab) and the Speakeasy SDK Generation GitHub Action (opens in a new tab). The workflow automates the process of:

Downloading or loading the OpenAPI document from a URL or repository.
Validating the OpenAPI document.
Generating SDKs for multiple languages.
Committing the generated SDKs to the repository or opening a pull request (PR).

Example Workflow File


name: SDK Generation
permissions:
  checks: write
  contents: write
  pull-requests: write
  statuses: write
on:
  workflow_dispatch:
    inputs:
      force:
        description: Force SDK generation, even if no changes are detected.
        type: boolean
        default: false
jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
    with:
      speakeasy_version: latest
      force: ${{ github.event.inputs.force }}
      mode: pr
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

Step-by-Step Guide

1. Initialize SDK Repository

Create a new GitHub repository to host the autogenerated SDKs. It is recommended to use a separate repository for each SDK, but a monorepo is also supported.

2. Generate SDK Workflow Configuration

Run the Speakeasy CLI to configure the SDK generation workflow. This command creates the necessary workflow files.


speakeasy configure github

After running the command, .speakeasy/workflow.yaml and .github/workflows/sdk_generation.yaml will be created. These files define the SDK generation workflow and the associated GitHub Action.

Screenshot of the terminal after successfully running Speakeasy configure Github.

If further customization is needed, manual configuration of the workflow files is available.

3. Set Up GitHub Secrets

Configure GitHub secrets for authentication:

Navigate to Settings > Secrets & Variables > Actions in your GitHub repository.
Add a new secret named SPEAKEASY_API_KEY which can be obtained from the Speakeasy dashboard.

4. Push to GitHub

Commit and push the generated workflow files to the repository. To test your github action without modifying any Github branches put the action into mode: test.

Navigate to Actions in the GitHub repository to trigger the SDK generation workflow manually or wait for it to run automatically. A green checkmark indicates successful workflow completion. If the publishing step has not been configured, it will be skipped.

https://github.com/speakeasy-sdks/example/actions/runs/9900330987

A screenshot of a successful generate flow.

For details on package publishing, refer to the Publishing SDKs guide.

5. GitHub Actions Workflow Permissions

If the error 403 GitHub Actions is not permitted to create or approve pull requests occurs, the repository’s GitHub Actions permissions must be updated.

Navigate to Settings > Actions > Workflow permissions and adjust the permissions accordingly.

https://github.com/speakeasy-sdks/example/settings/actions

Configure Remote URLs for Schemas

Warning

Remote URLs for OpenAPI schemas must remain stable. Dynamically constructed URLs in workflow files are not supported.

If the OpenAPI schema is hosted in another repository or at a remote URL, set the source as the remote URL in .speakeasy/workflow.yaml. Use the following command to add the remote URL:

To authenticate the remote URL, provide a token or key stored as an environment variable (e.g., $OPENAPI_DOC_TOKEN).

Add a GitHub Secret (opens in a new tab) with the same name and value as the token or key.