Automate Builds and Build Previews

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

If your OpenAPI spec isn't updated with GitHub pull requests, or you use another version control system like GitLab, 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 build previews

Builds triggered by pull request updates are called build previews. Build previews allow you to see changes to your Stainless-generated SDKs before you merge changes to your OpenAPI spec.

note

Before you enable build previews, make sure your team is familiar with them and wants them turned on. If your team isn't expecting them, build previews can be perceived as unwelcome noise instead of a powerful boon to your development process.

After you set up build previews, pull requests to your GitHub repository that will change your OpenAPI spec when merged will build your SDKs, then a comment will be added to your pull request with the 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 you wish. 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 build previews are triggered by the Build Stainless GitHub Action. Once you have the action installed, your .github/workflows/stainless.yml file should contain a job similar to the following which controls build previews:

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 }}

To disable build previews, comment out or remove the preview job.

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

Set up automatic builds

Automatic builds are similar to build previews, except these builds only happen when a pull request that modifies your OpenAPI spec is merged.

This section of your .github/workflows/stainless.yml file controls regular automatic builds:

jobs:
  # ...
  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 generally recommend setting up automatic builds and build previews as described above when possible, but if your OpenAPI spec isn't stored in a GitHub repo or you don't use pull requests to update it there are alternatives.

The options below are simpler and more flexible than automatic builds and build previews, but they're less powerful.

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. After setting up the action, pushes to your repository that update the 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.