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 Generationpermissions: checks: write contents: write pull-requests: write statuses: writeon: workflow_dispatch: inputs: force: description: Force SDK generation, even if no changes are detected. type: boolean default: falsejobs: 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.
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.
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.
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.