Automate codegen with alternative workflows

We recommend using preview builds instead of the workflows documented on this page. Preview builds let you to see codegen results before you ship changes to your API, which provides a better and safer development experience.

The workflows below should only be used if you don’t meet the requirements for preview builds, or if you’ve tried preview builds and determined they aren’t suitable for your use case.

If you can’t use preview builds, we provide two alternative ways to automate codegen:

• Push-based workflow: If you keep your OpenAPI spec in a GitHub or GitLab repository, but you don’t use pull/merge requests to make changes to it, use this workflow
• Polling workflow: If your OpenAPI spec is available at a stable URL, use this workflow

Push-based workflow

If you make changes to your OpenAPI spec using direct commits in GitHub or GitLab without pull/merge requests, install our GitHub action to automate codegen.

1 Set up authentication for the workflow

The GitHub workflow 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 authentication 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

Now add your API key as a secret so the workflow you add in the next step can use it:

• If you’re using GitHub: Add your API key as a secret in your GitHub repository with the name STAINLESS_API_KEY
• If you’re using GitLab: The workflow uses the $STAINLESS_API_KEY CI/CD variable, which you should configure using GitLab’s UI

See the next step and our example workflows for more details.

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-push.yml workflow file:

.github/workflows/stainless-push.yml

name: Build SDKs on push

on:
  push:
    branches:
      - main

env:
      # 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

      # The commit message to use for the SDK builds. Use a commit message in the
      # conventional commits format: https://www.conventionalcommits.org/en/v1.0.0/
      COMMIT_MESSAGE: "feat(api): update api"

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

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build SDK
        uses: stainless-api/upload-openapi-spec-action/build@v1
        with:
          stainless_api_key: ${{ secrets.STAINLESS_API_KEY }}
          org: ${{ env.STAINLESS_ORG }}
          project: ${{ env.STAINLESS_PROJECT }}
          oas_path: ${{ env.OAS_PATH }}

This workflow contains one job:

• build - Runs when a commit is pushed to the branch you specify (default is main) to trigger codegen using the latest commit on that branch

3 Configure the workflow

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

This workflow requires the following GitHub permissions:

• id-token: write for GitHub OIDC authentication
• 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.

URL polling workflow

If your OpenAPI spec is available at a stable URL, Stainless can poll that URL to detect API changes and trigger codegen.

This approach checks for updates hourly; if you want more responsive updates use the push-based workflow instead.

Set up polling

1. In the Stainless dashboard, navigate to your project
2. Go to Release > Setup OpenAPI spec sync > Fetch URL
3. Enter the URL for your OpenAPI spec in the Spec URL field
4. Press the Fetch Spec button

Once polling is set up, Stainless will look for changes to your OpenAPI spec every hour. If changes are found, codegen will be triggered.

Check for changes manually

You can tell Stainless to check for changes manually at any time by pressing the Fetch Spec button in your dashboard.