---
title: Automate codegen with alternative workflows | Stainless docs
description: Use a push-based workflow or poll your OpenAPI spec to trigger codegen after you make changes to your API
---

We recommend using [preview builds](/docs/guides/preview-builds/index.md) 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](/docs/guides/preview-builds/index.md), we provide two alternative ways to automate codegen:

- **[Push-based workflow](#push):** 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](#poll):** 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](https://docs.github.com/en/actions/concepts/security/openid-connect).

If you’re not using GitHub or can’t install the Stainless GitHub app, [use an API key to authenticate instead](#api-key-authentication).

To install the Stainless GitHub app:

1. Open your [Stainless dashboard](https://app.stainless.com)
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](https://app.stainless.com/org/default/settings)
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](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-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](https://docs.gitlab.com/ci/variables/#define-a-cicd-variable-in-the-ui)

See the [next step](#add-the-workflow) and our [example workflows](https://github.com/stainless-api/upload-openapi-spec-action/blob/main/examples) 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](https://github.com/stainless-api/upload-openapi-spec-action/blob/main/README.md) 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](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions):

- `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](https://github.com/stainless-api/upload-openapi-spec-action/blob/main/README.md) and our [example workflow files](https://github.com/stainless-api/upload-openapi-spec-action/tree/main/examples).

## 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](#push) 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.