Use preview builds to see codegen results before API changes go live

Preview builds are builds of your SDKs and other codegen targets based on OpenAPI spec changes in pull/merge requests you haven’t merged yet. Once set up, preview builds provide several advantages over other development workflows:

• New preview builds are generated automatically when you open or update a pull/merge request that will change your OpenAPI spec; there’s no extra steps or friction
• Preview build status, links, and other useful information is added to your pull/merge requests as a comment so you can see and test codegen results immediately, without changing contexts
• When it’s time to ship, your release builds will be based on your most recent preview builds, so you can be confident they’ll look and work the way you expect with no surprises

Requirements

Preview builds require the following:

• Your OpenAPI spec must be in either a GitHub or GitLab repository
• Changes to your OpenAPI spec must be made with pull/merge requests

If you don’t meet these requirements you can still automate codegen using a push-based or URL polling workflow.

Set up preview builds

Preview builds add automated comments to pull/merge requests. We recommend you discuss the workflow outlined below with your team before enabling preview builds so everyone knows what to expect.

1 Set up authentication for the workflow

The GitHub action that powers preview builds requires authentication. We recommend you install the Stainless GitHub app to provide authentication via OIDC.

If you’re not using GitHub or can’t install the Stainless GitHub app, use an API key to authenticate instead.

To install the Stainless GitHub app:

1. Open your Stainless dashboard
2. If needed, navigate to the organization/project where you want to enable preview builds
3. Go to the Release tab at the top and make sure Production repos is selected on the left
4. Press the Install Stainless App button
5. Follow the steps to complete the installation flow and give the Stainless app access to the repositories where you want to enable preview builds

By default All repositories are selected, but we recommend you only select the repository that contains the OpenAPI spec you want to use with Stainless.

Alternative: authenticate with an API key

If you don’t have admin permissions on GitHub, you’re using GitLab, or you’d prefer not to install the Stainless GitHub app, you can authenticate manually with an API key instead:

1. Navigate to your organization’s settings page
2. If you have more than one organization, make sure the correct one is selected
3. Click Create new API key
4. Add the API key to your workflow file during the next step and reference our example workflow that uses API key authentication as needed.

2 Add the workflow to your repository

Instructions for GitHub are shown below, but our workflow is also compatible with GitLab. See the workflow’s README file for further details.

In the GitHub repository where you make changes to your OpenAPI spec, add the following .github/workflows/stainless.yml workflow file:

.github/workflows/stainless.yml

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:
  # TODO: Stainless organization name.
  STAINLESS_ORG: YOUR_ORG

  # TODO: Stainless project name.
  STAINLESS_PROJECT: YOUR_PROJECT

  # TODO: Path to your OpenAPI spec.
  OAS_PATH: YOUR_OAS_PATH

  # Path to your Stainless config. Optional; only provide this if you prefer
  # to maintain the ground truth Stainless config in your own repo.
  CONFIG_PATH: YOUR_CONFIG_PATH

  # When to fail the job based on build conclusion.
  # Options: "never" | "note" | "warning" | "error" | "fatal".
  FAIL_ON: error

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 }}
          config_path: ${{ env.CONFIG_PATH }}
          fail_on: ${{ env.FAIL_ON }}

  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 }}
          config_path: ${{ env.CONFIG_PATH }}
          fail_on: ${{ env.FAIL_ON }}

This workflow contains two jobs:

• preview - Runs when a pull request is opened or updated to create a preview build with the changes from your pull request
• merge - Runs when a pull request is merged to create a release build

The merge job depends on the preview job, so you can’t use the merge job by itself. If you want to automate codegen only when your OpenAPI spec changes, without preview builds, we have alternative push-based and URL polling workflows you can use.

3 Configure the workflow

Update the STAINLESS_ORG, STAINLESS_PROJECT, and OAS_PATH environment variables in this workflow (each one has a TODO comment) to match your organization, project, and OpenAPI spec file path, respectively.

This workflow requires the following GitHub permissions:

• id-token: write for GitHub OIDC authentication
• pull-requests: write for adding preview build comments to pull requests
• contents: read to check out your repository’s code to read your OpenAPI spec and config files

For more configuration details, see the workflow’s README file and our example workflow files.

4 Secure public repositories

If your GitHub repository is public, make sure you require approval for workflows from forked pull requests to prevent unauthorized access to your OIDC tokens or secrets:

1. Go to your repository on GitHub
2. Navigate to Settings > Actions > General
3. Under Fork pull request workflows from outside collaborators select the Require approval for all outside collaborators option

See GitHub’s documentation for more details.

Use preview builds

Once preview builds are set up, they’ll be triggered automatically as you work on your API so you can see and test codegen results before you ship changes.

Trigger a preview build

Open or update a pull/merge request which changes your OpenAPI spec to trigger a preview build.

Preview build comments

Stainless will add a comment to your pull/merge request when a preview build is triggered:

The comment contains the following:

• The commit message Stainless will use when you merge your changes (which you can edit by editing the comment)
• Build results for each build target
• Links to the Stainless studio and the code for each target

For some build targets, the comment will also include instructions for downloading and installing the preview build of the SDK or tool so you can test it locally.

Iterate

If you need to make changes you can do any of the following:

• Update your pull/merge request with adjustments to your OpenAPI spec
• Modify your Stainless config in the Studio using the links in the Stainless comment
• Add or modify custom code in your preview builds

Release

When everything looks and works as it should, merge the changes to your OpenAPI spec to produce final builds based on your most recent preview builds.