GitHub Actions for building Stainless SDKs and previewing changes to an SDK from a pull request. Refer to our docs on automating builds for more information.

Support for GitLab CI is available. See the GitLab example.

The action supports two authentication methods:

GitHub OIDC (recommended): Install the Stainless GitHub App in your GitHub organization and link it to your Stainless organization. The app doesn't need access to the repository containing the workflow — just the org-level installation is enough. The action will authenticate automatically using GitHub OIDC. This is the default method shown in our examples.

With OIDC (short for OpenID Connect), there's no secret to set up or rotate — GitHub mints a short-lived, cryptographically signed token for each workflow run that can be validated by Stainless.

API keys: Generate an API key from your Stainless organization dashboard and add it as a STAINLESS_API_KEY secret. This works well for getting started or when you don't have admin permissions to install the GitHub App. See pull_request_api_key.yml for the workflow setup.

GitLab CI: OIDC isn't yet supported. Use the API key method and set the STAINLESS_API_KEY environment variable. See the template files in build/gitlab-ci.yml, merge/gitlab-ci.yml, and preview/gitlab-ci.yml.

Add a workflow file to the repository that contains your OpenAPI spec:

name: Build SDKs for pull request

on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - closed

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: true

env:
  STAINLESS_ORG: YOUR_ORG
  STAINLESS_PROJECT: YOUR_PROJECT
  OAS_PATH: YOUR_OAS_PATH

jobs:
  preview:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Run preview builds
        uses: stainless-api/upload-openapi-spec-action/preview@v1
        with:
          org: ${{ env.STAINLESS_ORG }}
          project: ${{ env.STAINLESS_PROJECT }}
          oas_path: ${{ env.OAS_PATH }}

  merge:
    if: github.event.action == 'closed' && github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Run merge build
        uses: stainless-api/upload-openapi-spec-action/merge@v1
        with:
          org: ${{ env.STAINLESS_ORG }}
          project: ${{ env.STAINLESS_PROJECT }}
          oas_path: ${{ env.OAS_PATH }}

Then, pull requests to your GitHub repository that update OpenAPI spec or Stainless config will build your SDKs and make a comment with the results.

Note: the merge job depends on the preview job, so you can't use just the merge job alone. See our docs for more details.

For more details about the input parameters, see the example workflow file.

For more examples of usage, including push-based workflows, using code samples, integration with docs platforms, and testing preview builds, see the examples directory.

If your GitHub repository is public, require approval for workflows from fork PRs to prevent untrusted contributors from accessing OIDC tokens or secrets.

Go to Settings → Actions → General, then under "Fork pull request workflows from outside collaborators", select "Require approval for all outside collaborators".

See GitHub's docs for more details.

This repository provides four GitHub actions:

• stainless-api/upload-openapi-spec-action/build - Build SDKs for a Stainless project. See the action definition for input parameters.

• stainless-api/upload-openapi-spec-action/preview - Preview SDK changes from a pull request. See the action definition for input parameters.

• stainless-api/upload-openapi-spec-action/merge - Merge SDK changes from a pull request. See the action definition for input parameters.

• stainless-api/upload-openapi-spec-action/checkout-pr-ref - Checkout the base or head commit for previewing changes. See the action definition for input parameters.

All except checkout-pr-ref work in GitLab CI.

The preview and merge actions output an install_url for each SDK language. You can use this to test builds directly from the Stainless package server before merging. See the SDK usage example.

These actions use semantic versioning, and you can pin your action to a major (v1), minor (v1.0), or patch (v1.0.0) version. The public API includes:

• The inputs to each action, and their expected format.

• The format of pull request comments.

• The name and format of the file written to documented_spec_path.

The public API does not include:

• The format of the outcomes and base_outcomes outputs.