Set Up Generation Workflows on Github

TIP

For most use cases, we recommend setting up the following workflows automatically by running speakeasy configure github in the root of your SDK repository and committing any generated files to your repo source. For a walkthrough of how this command works, please see this docs page.

Directly creating the workflow files below is only recommended for custom CI/CD workflows and users who are familiar with the Github Workflow syntax (opens in a new tab).

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: Generate
permissions:
    checks: write
    contents: write
    pull-requests: write
    statuses: write
"on":
    workflow_dispatch:
        inputs:
            force:
                description: Force generation of SDKs
                type: boolean
                default: false
jobs:
    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: Generate
permissions:
    checks: write
    contents: write
    pull-requests: write
    statuses: write
"on":
    workflow_dispatch:
        inputs:
            force:
                description: Force generation of SDKs
                type: boolean
                default: false
jobs:
    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: Generate
permissions:
    checks: write
    contents: write
    pull-requests: write
    statuses: write
"on":
    workflow_dispatch:
        inputs:
            force:
                description: Force generation of SDKs
                type: boolean
                default: false
jobs:
    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: Generate
permissions:
    checks: write
    contents: write
    pull-requests: write
    statuses: write
"on":
    workflow_dispatch:
        inputs:
            force:
                description: Force generation of SDKs
                type: boolean
                default: false
jobs:
    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: Generate
permissions:
    checks: write
    contents: write
    pull-requests: write
    statuses: write
"on":
    workflow_dispatch:
        inputs:
            force:
                description: Force generation of SDKs
                type: boolean
                default: false
jobs:
    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).

`github_access_token`

Required The default GitHub access token with write access to the repo.


name: Generate
permissions:
    checks: write
    contents: write
    pull-requests: write
    statuses: write
"on":
    workflow_dispatch:
        inputs:
            force:
                description: Force generation of SDKs
                type: boolean
                default: false
jobs:
    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.