Automate builds and preview builds

Automatic builds of your SDKs can be triggered when your OpenAPI spec changes. If your OpenAPI spec is in a GitHub or GitLab repository, and you use pull or merge requests to update it, we recommend you set up automatic preview builds and automatic merge builds.

If your OpenAPI spec isn’t updated with GitHub or GitLab pull/merge requests, or you use another version control system, you can use one of our other options to automate builds.

Here’s an overview of how code flows from your repository to your end users:

Set up automatic preview builds

Builds triggered by updates to a pull request that will modify your OpenAPI spec are called preview builds. Preview builds allow you to see changes to your Stainless-generated SDKs before you actually merge changes, which make them a useful tool during development. We recommend using preview builds if possible, but we also have options for automating builds in other ways.

Before you enable preview builds, make sure your team is familiar with them and wants them turned on. Unexpected preview builds can be perceived as unwelcome noise instead of a powerful boon to your development process.

Once set up, preview builds of your SDKs are triggered automatically by pull requests that will change your OpenAPI spec. A comment will be added to your pull request with the build results.

The comment shows the commit message that will be used when your change is merged. You can edit the comment to change the commit message. If your change adds new diagnostics, causes a merge conflict, or causes a fatal error, the comment will let you know. For some languages, the comment will include instructions for installing the preview SDK so you can try it out locally.

SDK preview builds are triggered by the Build Stainless GitHub Action (which also supports GitLab). Once you have the action installed, your .github/workflows/stainless.yml file should contain a job similar to the following which controls preview builds:

jobs:
  preview:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: 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:
          stainless_api_key: ${{ secrets.STAINLESS_API_KEY }}
          org: ${{ env.STAINLESS_ORG }}
          project: ${{ env.STAINLESS_PROJECT }}
          oas_path: ${{ env.OAS_PATH }}
  merge:
    # ...

For more details about setting up preview builds, have a look at the Build Stainless GitHub Actions readme.

Automatic merge builds

Automatic merge builds are similar to preview builds, except these builds only happen when a pull request that modifies your OpenAPI spec is actually merged. Automatic merge builds depend on a previous preview build running and creating a branch, so you can’t use this feature without preview builds. If you don’t want preview builds, you can automate builds in other ways.

The merge job in your .github/workflows/stainless.yml file controls automatic builds:

jobs:
  preview:
    # ...
  merge:
    if: github.event.action == 'closed' && github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: 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:
          stainless_api_key: ${{ secrets.STAINLESS_API_KEY }}
          org: ${{ env.STAINLESS_ORG }}
          project: ${{ env.STAINLESS_PROJECT }}
          oas_path: ${{ env.OAS_PATH }}

For more details about setting up automatic builds, have a look at the Build Stainless GitHub Actions readme.

Automate builds in other ways

We recommend using preview builds as described above, but if you don’t want preview builds or can’t use them (e.g., if you’re not using GitHub or GitLab, or you don’t use pull/merge requests to update your OpenAPI spec) you can use one of the options below instead. These options are less powerful, but have the advantage of being simpler and more flexible.

The options in this section are designed to trigger automatic builds of your SDKs when either the OpenAPI spec on your main branch is updated, or when your public-facing OpenAPI spec changes.

Trigger builds when a GitHub or GitLab commit is pushed

If you store your OpenAPI spec in a GitHub or GitLab repository, you can use our CI component to build your SDKs when a commit is pushed to your primary branch. After setting up the action, pushes to your repository that update your OpenAPI spec will build your SDKs.

For setup instructions and more details, see the push workflows documentation in our Build Stainless GitHub Actions.

Set up OpenAPI spec polling to trigger builds

If you have a stable URL to your OpenAPI spec, you can set up polling in the Stainless dashboard.

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

Once polling is set up, Stainless will check for changes to the OpenAPI spec at the specified link every hour. You can also manually trigger a check in the dashboard.