Speakeasy Workflow File

Workflow configuration file. Read more at https://www.speakeasy.com/docs/workflow-file-reference

Type object
File match **/.speakeasy/workflow.yaml
Schema URL https://catalog.lintel.tools/schemas/schemastore/speakeasy-workflow-file/latest.json
Source https://raw.githubusercontent.com/speakeasy-api/sdk-gen-config/main/schemas/workflow.schema.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Properties

workflowVersion string required

The version of the workflow schema

Constant: "1.0.0"
dependents Record<string, object>

A map of dependent names to dependent configurations, used to define external repositories and their locations

sources Record<string, object>

A map of source names to source configurations, where the output is an OpenAPI document

speakeasyVersion const: "latest" | const: "pinned" | string
targets Record<string, object>

A map of target names to target configurations, where the output is a speakeasy generation target

Definitions

WorkflowAuth object

Authentication information for the document (optional)

authHeader string required

A HTTP Header Name

authSecret string required

A HTTP Header Value

WorkflowCLI object
gpgPassPhrase string required
gpgPrivateKey string required
WorkflowCodeSamples object

Code samples configuration. See https://www.speakeasy.com/guides/openapi/x-codesamples

blocking null | boolean

Defaults to true. If false, code samples failures will not consider the workflow as failed

disabled null | boolean

Optional flag to disable code samples.

labelOverride object
2 nested properties
fixedValue null | string

Optional fixed value for the label.

omit null | boolean

Optional flag to omit the label.

langOverride null | string

Optional language override for the code sample. Default behavior is to auto-detect.

output string

The output file name

registry object

The openapi registry configuration

2 nested properties
location string required

The registry location to use (for snapshotting/change tracking)

tags string[]

The list of tags to use for the registry

style null | string

Optional style for the code sample, one of 'standard' or 'readme'. Default is 'standard'.

WorkflowCodeSamplesLabelOverride object
fixedValue null | string

Optional fixed value for the label.

omit null | boolean

Optional flag to omit the label.

WorkflowDependent object

A dependent configuration for external repositories

location string required

The local path to the repository

cloneCommand string

Optional command to clone the repository

WorkflowDeployment object

Gram deployment configuration for MCP servers. Presence of this block enables deployment.

project string

Gram project name. Defaults to Gram's authenticated org context.

WorkflowDocument object

A local or remote document.

location string required

The location to resolve the document at. E.g. a file name, relative location, or a HTTP URL

minLength=1
authHeader string

A HTTP Header Name

authSecret string

A HTTP Header Value

modelNamespace string

The model namespace/group for component schemas (used when merging multiple documents)

WorkflowFallbackCodeSamples object
fallbackCodeSamplesLanguage string required
WorkflowFilterOperationsOptions object
operations string required

Comma-separated list of operations to filter

exclude null | boolean

Exclude the specified operations (mutually exclusive with include)

include null | boolean

Include the specified operations (mutually exclusive with exclude)

WorkflowJava object
gpgPassPhrase string required
gpgSecretKey string required
ossrhPassword string required
ossrhUsername string required
useSonatypeLegacy boolean required
WorkflowMCPRegistry object
auth string required

Authentication method for the MCP Registry. Use 'github-oidc' (recommended, no token needed) for io.github.* namespaces in GitHub Actions, 'github' with a PAT, or 'dns' for custom domain namespaces.

Values: "github-oidc" "github" "dns"
token string

Authentication token. Not needed for github-oidc. For github auth, a GitHub PAT with read:org and read:user scopes. For dns auth, the Ed25519 private key.

WorkflowMockServer object
enabled null | boolean

Defaults to true. If false, the mock API server will not be started.

WorkflowNPM object
token string required
WorkflowNormalizeOptions object
prefixItems null | boolean
WorkflowNuget object
apiKey string required
WorkflowOverlay WorkflowDocument | object
WorkflowPackagist object
token string required
username string required
WorkflowPublishing object

The publishing configuration. See https://www.speakeasy.com/docs/workflow-reference/publishing-reference

cli object
2 nested properties
gpgPassPhrase string required
gpgPrivateKey string required
java object
5 nested properties
gpgPassPhrase string required
gpgSecretKey string required
ossrhPassword string required
ossrhUsername string required
useSonatypeLegacy boolean required
mcpRegistry object
2 nested properties
auth string required

Authentication method for the MCP Registry. Use 'github-oidc' (recommended, no token needed) for io.github.* namespaces in GitHub Actions, 'github' with a PAT, or 'dns' for custom domain namespaces.

Values: "github-oidc" "github" "dns"
token string

Authentication token. Not needed for github-oidc. For github auth, a GitHub PAT with read:org and read:user scopes. For dns auth, the Ed25519 private key.

npm object
1 nested properties
token string required
nuget object
1 nested properties
apiKey string required
packagist object
2 nested properties
token string required
username string required
pypi object
2 nested properties
token string

PyPI API token for token-based authentication. Not required if using trusted publishing.

useTrustedPublishing null | boolean

Use OIDC trusted publishing instead of token-based authentication. See https://docs.pypi.org/trusted-publishers/

rubygems object
1 nested properties
token string required
terraform object
2 nested properties
gpgPassPhrase string required
gpgPrivateKey string required
WorkflowPyPi object
token string

PyPI API token for token-based authentication. Not required if using trusted publishing.

useTrustedPublishing null | boolean

Use OIDC trusted publishing instead of token-based authentication. See https://docs.pypi.org/trusted-publishers/

WorkflowRubyGems object
token string required
WorkflowSource object

A source configuration

inputs array | null required

A list of input documents (OpenAPI Specifications). These will be merged together

minItems=1
output null | string

The output file name (optional)

overlays WorkflowOverlay[]

A list of overlay files (OpenAPI Overlay Specification)

registry object

The openapi registry configuration

2 nested properties
location string required

The registry location to use (for snapshotting/change tracking)

tags string[]

The list of tags to use for the registry

ruleset null | string

The linting ruleset to use (optional)

transformations WorkflowTransformation[]

A list of transformations to apply to the OpenAPI document

WorkflowSourceRegistry object

The openapi registry configuration

location string required

The registry location to use (for snapshotting/change tracking)

tags string[]

The list of tags to use for the registry

WorkflowTarget object
source string required
target string required
Values: "cli" "csharp" "go" "java" "mcp-typescript" "php" "python" "ruby" "swift" "terraform" "typescript" "unity" "postman"
codeSamples object

Code samples configuration. See https://www.speakeasy.com/guides/openapi/x-codesamples

7 nested properties
blocking null | boolean

Defaults to true. If false, code samples failures will not consider the workflow as failed

disabled null | boolean

Optional flag to disable code samples.

labelOverride object
2 nested properties
fixedValue null | string

Optional fixed value for the label.

omit null | boolean

Optional flag to omit the label.

langOverride null | string

Optional language override for the code sample. Default behavior is to auto-detect.

output string

The output file name

registry object

The openapi registry configuration

2 nested properties
location string required

The registry location to use (for snapshotting/change tracking)

tags string[]

The list of tags to use for the registry

style null | string

Optional style for the code sample, one of 'standard' or 'readme'. Default is 'standard'.

deployment object

Gram deployment configuration for MCP servers. Presence of this block enables deployment.

1 nested properties
project string

Gram project name. Defaults to Gram's authenticated org context.

output null | string
publish object

The publishing configuration. See https://www.speakeasy.com/docs/workflow-reference/publishing-reference

9 nested properties
cli object
2 nested properties
gpgPassPhrase string required
gpgPrivateKey string required
java object
5 nested properties
gpgPassPhrase string required
gpgSecretKey string required
ossrhPassword string required
ossrhUsername string required
useSonatypeLegacy boolean required
mcpRegistry object
2 nested properties
auth string required

Authentication method for the MCP Registry. Use 'github-oidc' (recommended, no token needed) for io.github.* namespaces in GitHub Actions, 'github' with a PAT, or 'dns' for custom domain namespaces.

Values: "github-oidc" "github" "dns"
token string

Authentication token. Not needed for github-oidc. For github auth, a GitHub PAT with read:org and read:user scopes. For dns auth, the Ed25519 private key.

npm object
1 nested properties
token string required
nuget object
1 nested properties
apiKey string required
packagist object
2 nested properties
token string required
username string required
pypi object
2 nested properties
token string

PyPI API token for token-based authentication. Not required if using trusted publishing.

useTrustedPublishing null | boolean

Use OIDC trusted publishing instead of token-based authentication. See https://docs.pypi.org/trusted-publishers/

rubygems object
1 nested properties
token string required
terraform object
2 nested properties
gpgPassPhrase string required
gpgPrivateKey string required
testing object

Target testing configuration. By default, targets are not tested as part of the workflow.

2 nested properties
enabled null | boolean

Defaults to false. If true, the target will be tested as part of the workflow.

mockServer object
1 nested properties
enabled null | boolean

Defaults to true. If false, the mock API server will not be started.

WorkflowTerraform object
gpgPassPhrase string required
gpgPrivateKey string required
WorkflowTesting object

Target testing configuration. By default, targets are not tested as part of the workflow.

enabled null | boolean

Defaults to false. If true, the target will be tested as part of the workflow.

mockServer object
1 nested properties
enabled null | boolean

Defaults to true. If false, the mock API server will not be started.

WorkflowTransformation object
cleanup null | boolean

Clean up the OpenAPI document

filterOperations object
3 nested properties
operations string required

Comma-separated list of operations to filter

exclude null | boolean

Exclude the specified operations (mutually exclusive with include)

include null | boolean

Include the specified operations (mutually exclusive with exclude)

format null | boolean
jqSymbolicExecution null | boolean
normalize object
1 nested properties
prefixItems null | boolean
removeUnused null | boolean

Remove unused components from the OpenAPI document

WorkflowVersion const: "latest" | const: "pinned" | string