# Workflow matrix

<Callout title="Tip">
  To quickly set up the workflow, run `speakeasy configure github` in the root
  of the SDK repository. This automates the setup and commits the necessary
  files. For more complex or custom configurations, the following is supported.
</Callout>

## Workflow inputs

```yml
"on":
  workflow_dispatch:
    inputs:
      force:
        description: Force generation of SDKs
        type: boolean
        default: false
      set_version:
        description: optionally set a specific SDK version
        type: string
      runs-on:
        description: Runner to use for the workflow (e.g., large-ubuntu-runner)
        type: string
        default: ubuntu-latest
```

The inputs to the workflow determine how the SDKs will be generated.

## Workflow jobs

The generate job utilizes the Speakeasy SDK generation action. It references the `workflow-executor.yaml` from the `sdk-generation-action` repo, which handles the core operations like pulling the OpenAPI document, validating it, and generating the SDKs.

In `direct` mode, this workflow also handles publishing the generated SDKs to package registries (npm, PyPI, Maven, etc.) as part of the same run. In `pr` mode, publishing is handled separately by the `sdk_publish.yaml` workflow after the generated PR is merged.

### With

```yml
jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
    with:
      force: ${{ github.event.inputs.force }}
      mode: pr
      set_version: ${{ github.event.inputs.set_version }}
      speakeasy_version: latest
      github_repository: acme-org/acme-sdk-typescript
      runs-on: ${{ github.event.inputs.runs-on }}
```

### Secrets

```yml
secrets:
  github_access_token: ${{ secrets.GITHUB_TOKEN }}
  npm_token: ${{ secrets.NPM_TOKEN }}
  speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
```

## PyPI trusted publishing job

For Python SDKs using [trusted publishing](/docs/sdks/publish-sdk#python-pypi-trusted-publishing), add a `publish-pypi` job that runs after the main publish job. This job uses OIDC to authenticate with PyPI, eliminating the need for a `PYPI_TOKEN` secret.

```yml
publish-pypi:
  needs: publish
  if: ${{ needs.publish.outputs.python_regenerated == 'true' &&
          needs.publish.outputs.publish_python == 'true' &&
          needs.publish.outputs.use_pypi_trusted_publishing == 'true' }}
  runs-on: ubuntu-latest
  permissions:
    id-token: write
    contents: read
  steps:
    - uses: actions/checkout@v4
    - uses: speakeasy-api/sdk-generation-action/publish-pypi@v15
      with:
        python-directory: ${{ needs.publish.outputs.python_directory }}
        speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
        github_access_token: ${{ secrets.GITHUB_TOKEN }}
```

<Callout title="Important">
  The `id-token: write` permission is required at the job level for the OIDC token exchange with PyPI. The trusted publisher must also be configured on pypi.org for the target package.
</Callout>

## Workflow outputs

The workflow provides outputs that indicate which SDKs were regenerated and can trigger further actions in the pipeline, such as validating, testing, and publishing the SDKs.