Set Up Generation Workflows on Github
TIP
For most use cases, run speakeasy configure github
in the root of your SDK repository to automate workflow setup and commit the generated files; for custom CI/CD workflows or users familiar with GitHub Workflow syntax, manual creation can be used. Note that speakeasy configure
commands may overwrite any existing .github/ files, so it's not recommended to use both methods.
How Do Generation Workflows Work?
These workflows are powered through the SDK Generation GitHub Action (opens in a new tab). The Speakeasy SDK Generation Action & Workflows repository provides an action and workflow definitions to generate client SDKs from an OpenAPI document using the Speakeasy CLI (opens in a new tab).
You can use the action and workflows to manage CI/CD (that is, the automatic generation and publishing of client SDKs) in a repo containing the generated SDKs.
Using the Generation Workflow
Generation Workflow
The generation workflow is added as a file to your .github/workflows
folder. Here we will name it .github/workflows/sdk_generation.yaml
.
When you use the action in direct
mode, the generation workflow will generate SDKs. If you use the action in pr
mode, the generation workflow will generate SDKs and create a PR. Often, the merging of the PR is used to trigger the publishing workflow.
The generation workflow also runs several other steps by default (such as validating the provided OpenAPI document) and gives you warnings and errors in the workflow output that you can address.
Here is an example configuration of a generation workflow using the pr
mode of the action:
name: Generatepermissions: checks: write contents: write pull-requests: write statuses: write"on": workflow_dispatch: inputs: force: description: Force generation of SDKs type: boolean default: falsejobs: generate: uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15 with: force: ${{ github.event.inputs.force }} mode: pr secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
Generation
Direct Mode
In direct mode, the generation action does the following:
- Downloads the latest or pinned version of the Speakeasy CLI.
- Clones the associated repo.
- Downloads or loads the latest OpenAPI doc from a URL or the repo.
- Validates the OpenAPI doc.
- Checks for changes to the OpenAPI doc and the Speakeasy CLI version.
- Generates a new SDK for the configured languages, if necessary.
- Creates a commit with the new SDK (or SDKs) and pushes it to the repo.
- Optionally creates a GitHub release for the new commit.
PR Mode
In PR mode, the generation action does the following:
- Downloads the latest or pinned version of the Speakeasy CLI.
- Clones the associated repo.
- Creates a branch or updates an existing branch for the new SDK version.
- Downloads or loads the latest OpenAPI doc from a URL or the repo.
- Validates the OpenAPI doc.
- Checks for changes to the OpenAPI doc and the Speakeasy CLI version.
- Generates a new SDK for the configured languages, if necessary.
- Creates a commit with the new SDK (or SDKs) and pushes it to the repo.
- Creates a PR from the new branch to the main branch or updates an existing PR.
name: Generatepermissions: checks: write contents: write pull-requests: write statuses: write"on": workflow_dispatch: inputs: force: description: Force generation of SDKs type: boolean default: falsejobs: generate: uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15 with: force: ${{ github.event.inputs.force }} mode: pr secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
Direct Mode
In direct mode, the generation action does the following:
- Downloads the latest or pinned version of the Speakeasy CLI.
- Clones the associated repo.
- Downloads or loads the latest OpenAPI doc from a URL or the repo.
- Validates the OpenAPI doc.
- Checks for changes to the OpenAPI doc and the Speakeasy CLI version.
- Generates a new SDK for the configured languages, if necessary.
- Creates a commit with the new SDK (or SDKs) and pushes it to the repo.
- Optionally creates a GitHub release for the new commit.
PR Mode
In PR mode, the generation action does the following:
- Downloads the latest or pinned version of the Speakeasy CLI.
- Clones the associated repo.
- Creates a branch or updates an existing branch for the new SDK version.
- Downloads or loads the latest OpenAPI doc from a URL or the repo.
- Validates the OpenAPI doc.
- Checks for changes to the OpenAPI doc and the Speakeasy CLI version.
- Generates a new SDK for the configured languages, if necessary.
- Creates a commit with the new SDK (or SDKs) and pushes it to the repo.
- Creates a PR from the new branch to the main branch or updates an existing PR.
name: Generatepermissions: checks: write contents: write pull-requests: write statuses: write"on": workflow_dispatch: inputs: force: description: Force generation of SDKs type: boolean default: falsejobs: generate: uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15 with: force: ${{ github.event.inputs.force }} mode: pr secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
Inputs
speakeasy_api_key
Required The Speakeasy API key to use to authenticate the CLI run by the action. Create a new API key in the Speakeasy Platform (opens in a new tab).
name: Generatepermissions: checks: write contents: write pull-requests: write statuses: write"on": workflow_dispatch: inputs: force: description: Force generation of SDKs type: boolean default: falsejobs: generate: uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15 with: force: ${{ github.event.inputs.force }} mode: pr secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
github_access_token
Required The default GitHub access token with write access to the repo.
name: Generatepermissions: checks: write contents: write pull-requests: write statuses: write"on": workflow_dispatch: inputs: force: description: Force generation of SDKs type: boolean default: falsejobs: generate: uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15 with: force: ${{ github.event.inputs.force }} mode: pr secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
speakeasy_api_key
Required The Speakeasy API key to use to authenticate the CLI run by the action. Create a new API key in the Speakeasy Platform (opens in a new tab).
name: Generatepermissions: checks: write contents: write pull-requests: write statuses: write"on": workflow_dispatch: inputs: force: description: Force generation of SDKs type: boolean default: falsejobs: generate: uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15 with: force: ${{ github.event.inputs.force }} mode: pr secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
Workflow Log Outputs
python_regenerated
This will be true
if the Python SDK was regenerated.
python_directory
The directory the Python SDK was generated in.
typescript_regenerated
This will be true
if the TypeScript SDK was regenerated.
typescript_directory
The directory the TypeScript SDK was generated in.
go_regenerated
This will be true
if the Go SDK was regenerated.
go_directory
The directory the Go SDK was generated in.
java_regenerated
This will be true
if the Java SDK was regenerated.
java_directory
The directory the Java SDK was generated in.
php_regenerated
This will be true
if the PHP SDK was regenerated.
php_directory
The directory the PHP SDK was generated in.
terraform_regenerated
This will be true
if the Terraform provider was regenerated.
terraform_directory
The directory the Terraform provider was generated in.
ruby_regenerated
This will be true
if the Ruby SDK was regenerated.
ruby_directory
The directory the Ruby SDK was generated in.