docs: use combined build action in examples (#206)

* docs: use combined build action in examples

* update example readme

* Apply suggestions from code review

Co-authored-by: Justin Michael <justin@stainless.com>

---------

Co-authored-by: Justin Michael <justin@stainless.com>

Author: cjquines

README.md

@@ -25,7 +25,7 @@ workflow run that can be validated by Stainless.
 **API keys:** Generate an API key from your Stainless organization dashboard and add it as a `STAINLESS_API_KEY` secret. This works well for getting started or when you don't have admin permissions to install the GitHub App. See [pull_request_api_key.yml](./examples/pull_request_api_key.yml) for the workflow setup.
 
 > [!NOTE]
-> **GitLab CI:** OIDC isn't yet supported. Use the API key method and set the `STAINLESS_API_KEY` environment variable. See the template files in `build/gitlab-ci.yml`, `merge/gitlab-ci.yml`, and `preview/gitlab-ci.yml`.
+> **GitLab CI:** OIDC isn't yet supported. Use the API key method and set the `STAINLESS_API_KEY` environment variable. See the template files in `build/gitlab-ci.yml`.
 
 ## Usage
 
@@ -35,18 +35,17 @@ Add a workflow file to the repository that contains your OpenAPI spec:
 <summary><code>.github/workflows/stainless.yml</code></summary>
 
 ```yml
-name: Build SDKs for pull request
+name: Build Stainless SDKs
 
 on:
   pull_request:
-    types:
-      - opened
-      - synchronize
-      - reopened
-      - closed
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+  workflow_dispatch:
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 env:
@@ -55,41 +54,20 @@ env:
   OAS_PATH: YOUR_OAS_PATH
 
 jobs:
-  preview:
-    if: github.event.action != 'closed'
+  build:
     runs-on: ubuntu-latest
     permissions:
       contents: read
       pull-requests: write
       id-token: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         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 }}
-
-  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
+      - name: Run builds
+        uses: stainless-api/upload-openapi-spec-action/build@v1
         with:
           org: ${{ env.STAINLESS_ORG }}
           project: ${{ env.STAINLESS_PROJECT }}
@@ -101,11 +79,8 @@ jobs:
 Then, pull requests to your GitHub repository that update OpenAPI spec or
 Stainless config will build your SDKs and make a comment with the results.
 
-Note: the `merge` job depends on the `preview` job, so you can't use just
-the `merge` job alone. See [our docs](https://www.stainless.com/docs/guides/automate-updates) for more details.
-
 For more details about the input parameters, see the
-[example workflow](./examples/pull_request.yml) file.
+[example workflow](./examples/push.yml) file.
 
 For more examples of usage, including push-based workflows, using code samples,
 integration with docs platforms, and testing preview builds, see the [examples
@@ -116,11 +91,11 @@ directory](./examples).
 
 The workflows require the following [permissions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions):
 
-- **`id-token: write`** - Required for GitHub OIDC authentication. Allows the workflow to request an OIDC token from GitHub.
+- **`contents: read`** - Required for checking out the repository code to read the OpenAPI spec and config files.
 
-- **`pull-requests: write`** - Required for posting comments on pull requests with build results. If you don't need comments, you can set `make_comment: false` and remove this permission.
+- **`pull-requests: write`** - Required for posting comments on pull requests with build results. If you don't need comments, you can set `make_comment: false` and set the permission to `pull-requests: read`.
 
-- **`contents: read`** - Required for checking out the repository code to read the OpenAPI spec and config files.
+- **`id-token: write`** - Required for GitHub OIDC authentication. Allows the workflow to request an OIDC token from GitHub.
 
 </details>
 
@@ -142,10 +117,6 @@ This repository provides several GitHub actions:
 
 - `stainless-api/upload-openapi-spec-action/build` - Build SDKs for a Stainless project. See the [action definition](./build/action.yml) for input parameters.
 
-- `stainless-api/upload-openapi-spec-action/preview` - Preview SDK changes from a pull request. See the [action definition](./preview/action.yml) for input parameters.
-
-- `stainless-api/upload-openapi-spec-action/merge` - Merge SDK changes from a pull request. See the [action definition](./merge/action.yml) for input parameters.
-
 - `stainless-api/upload-openapi-spec-action/checkout-pr-ref` - Checkout the base or head commit for previewing changes. See the [action definition](./checkout-pr-ref/action.yml) for input parameters.
 
 ### Preparation Tools
@@ -156,7 +127,7 @@ This repository provides several GitHub actions:
 
 All except `checkout-pr-ref` work in GitLab CI.
 
-The `preview` and `merge` actions output an `install_url` for each SDK language. You can use this to test builds directly from the Stainless package server before merging. See the [SDK usage example](./examples/pull_request_sdk_usage.yml).
+The `build` action outputs an `install_url` for each SDK language. You can use this to test builds directly from the Stainless package server before merging. See the [SDK usage example](./examples/pull_request_sdk_usage.yml).
 
 ## Versioning
 

build/action.yml

@@ -124,19 +124,15 @@ outputs:
         "typescript": {
           "install_url": "https://pkg.stainless.com/...",
           "commit": {
-            "status": "completed",
-            "completed": {
-              "conclusion": "success",
-              "commit": {
-                "sha": "...",
-                "repo": {
-                  "branch": "...",
-                  "name": "...",
-                  "owner": "...",
-                  ...
-                },
+            "conclusion": "success",
+            "commit": {
+              "sha": "...",
+              "repo": {
+                "branch": "...",
+                "name": "...",
+                "owner": "...",
+                ...
               },
-              ...
             }
             ...
           },
@@ -155,19 +151,15 @@ outputs:
         "typescript": {
           "install_url": "https://pkg.stainless.com/...",
           "commit": {
-            "status": "completed",
-            "completed": {
-              "conclusion": "success",
-              "commit": {
-                "sha": "...",
-                "repo": {
-                  "branch": "...",
-                  "name": "...",
-                  "owner": "...",
-                  ...
-                },
+            "conclusion": "success",
+            "commit": {
+              "sha": "...",
+              "repo": {
+                "branch": "...",
+                "name": "...",
+                "owner": "...",
+                ...
               },
-              ...
             }
             ...
           },

examples/README.md

@@ -1,18 +1,18 @@
 # Example workflows
 
-There's two kinds of workflows, depending on how you manage your GitHub repo. Both workflows require you to provide your Stainless org and project names.
+All workflows require you to provide your Stainless org and project names.
 
 For authentication setup, see the [Authentication section](../README.md#authentication) in the main README.
 
-## Pull request workflows
+## GitHub Actions
 
-The main kind of workflows are the pull-request-based workflows, such as [pull_request.yml](./pull_request.yml). If all changes to your OpenAPI spec are made via pull requests, we recommend using this workflow. It has two jobs:
+We recommend you use [push.yml](./push.yml). It has a single `build` job that runs when you create or update pull requests and when you push to your main branch.  It can also be triggered manually if needed.  For pull requests, the `build` job creates a build of your SDK using the changes that will be introduced by the pull request, then it adds a comment to the pull request with links to a GitHub diff and installation commands. For pushes to your main branch, the `build` job creates a build of the SDK with the pushed changes.
 
-- `preview`, which runs when a pull request is opened or updated. The job creates a build of your SDK which includes only the changes introduced by the pull request. It also makes a comment on the pull request, with links to a GitHub diff, and installation commands for trying out your SDK.
+By default, the pull request workflow uses the title of the pull request as the commit message, but you can edit the comment on the pull request to change the commit message.
 
-- `merge`, which runs when a pull request is merged. The job creates a build of the SDK with the changes from the pull request, along with any [custom code](https://app.stainless.com/docs/guides/patch-custom-code#project-branches) added to the preview build.
+### API key authentication
 
-By default, the pull request workflow uses the title of the pull request as the commit message, but you can edit the comment on the pull request to change the commit message.
+If you prefer to authenticate with an API key instead of OIDC, use [pull_request_api_key.yml](./pull_request_api_key.yml).
 
 ### Fork pull requests
 
@@ -26,23 +26,25 @@ The workflow explicitly checks out the PR's code to read the OpenAPI spec. This
 
 If your OpenAPI spec is generated from your GitHub repo, via a shell script or other GitHub action, you will need to do some extra setup. This is because the action needs access to both the old OpenAPI spec and the new OpenAPI spec. See the example at [pull_request_generated.yml](./pull_request_generated.yml).
 
-Here, `checkout-pr-ref` will checkout the relevant base Git commit. The first command runs against the base Git commit, generating the old OpenAPI spec. Then, `checkout-pr-ref` will checkout the relevant head Git commit. The second command runs against the head Git commit, generating the new OpenAPI spec.
+Here, `checkout-pr-ref` will checkout the relevant base Git commit. The first command runs against the base Git commit, generating the old OpenAPI spec. Then, `checkout-pr-ref` will checkout the relevant head Git commit. The second command runs against the head Git commit, generating the new OpenAPI spec. These steps are conditioned on pull request events; on pushes to your main branch, only the current spec is needed.
+
+### Using SDK build outputs
 
-## Push workflows
+If you want to install and test SDK builds as part of your workflow, see [pull_request_sdk_usage.yml](./pull_request_sdk_usage.yml). This example demonstrates how to extract the `install_url` from the build outputs and use it to install the SDK for integration testing.
 
-The other kind of workflows are the push-based workflows, such as [push.yml](./push.yml). If for some reason you can't use the pull-request-based workflows, you can use this workflow. It has one job:
+## GitLab CI
 
-- `build`, which runs when a commit is pushed to a branch you specify. The job creates a build of your SDK against the latest commit on that branch.
+For GitLab projects, add the configuration from [push_gitlab.yml](./push_gitlab.yml) to your `.gitlab-ci.yml` file. The workflow uses a single `build-sdk` job that runs on merge requests and pushes to your main branch.
 
-In the examples, the push workflow is configured to use a generic commit message. You can change this to the message of the pushed commit by using `${{ github.event.head_commit.message }}`.
+If your OpenAPI spec is in a GitLab repo, see [merge_request_gitlab_generated.yml](./merge_request_gitlab_generated.yml) for additional instructions.
 
 ## Integration with docs platforms
 
-If your Stainless config has code samples configured, the `preview`, `merge`, and `build` actions also output a `documented_spec_path` containing a path to your OpenAPI spec with SDK code samples.
+If your Stainless config has code samples configured, the `build` action also outputs a `documented_spec_path` containing a path to a version of your OpenAPI spec with SDK code samples included.
 
-If you sync your OpenAPI spec with a [ReadMe API Reference](https://readme.com/), you can use the [Sync to ReadMe](https://github.com/marketplace/actions/rdme-sync-to-readme) GitHub action to upload the documented spec to ReadMe. You can see examples of this in the [pull_request_readme.yml](./pull_request_readme.yml) and [push_readme.yml](./push_readme.yml) files.
+If you sync your OpenAPI spec with a [ReadMe API Reference](https://readme.com/), use the [Sync to ReadMe](https://github.com/marketplace/actions/rdme-sync-to-readme) GitHub action to upload the documented spec to ReadMe. We have examples in the [push_readme.yml](./push_readme.yml) file.
 
-If you use [Mintlify's OpenAPI support](https://mintlify.com/docs/api-playground/openapi-setup#in-the-repo) for your API reference documentation, you can copy the documented spec to your Mintlify docs repo to update it. You can see examples of this in the [pull_request_mintlify.yml](./pull_request_mintlify.yml) and [push_mintlify.yml](./push_mintlify.yml) files.
+If you use [Mintlify's OpenAPI support](https://mintlify.com/docs/api-playground/openapi-setup#in-the-repo) for your API reference documentation, copy the documented spec to your Mintlify docs repo to update it. We have examples in the [push_mintlify.yml](./push_mintlify.yml) file.
 
 ## Spec preparation
 

examples/merge_request_gitlab.yml

@@ -1,9 +1,27 @@
+# Add this to your .gitlab-ci.yml file.
+
 include:
-  - remote: "https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/preview/gitlab-ci.yml"
-  - remote: "https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/merge/gitlab-ci.yml"
+  - remote: "https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/build/gitlab-ci.yml"
 
-.common:
+build-sdk:
+  extends: .build-sdk
+  only:
+    - merge_requests
+    # Set this to the branch of the repository that the `main` Stainless branch
+    # of your project gets its OpenAPI spec from. This is usually the default
+    # branch of your repository.
+    - main
   variables:
+    # A Stainless API key, which you can generate on the Stainless organization
+    # dashboard. Add this to your CI/CD variables:
+    # https://docs.gitlab.com/ci/variables/#add-a-cicd-variable-to-a-project
+    STAINLESS_API_KEY: $STAINLESS_API_KEY
+
+    # A GitLab token with permissions to read and write merge request comments.
+    # Add this to your CI/CD variables:
+    # https://docs.gitlab.com/ci/variables/#add-a-cicd-variable-to-a-project
+    GITLAB_TOKEN: $GITLAB_TOKEN
+
     # Stainless organization name.
     ORG: YOUR_ORG
 
@@ -17,22 +35,14 @@ include:
     # 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
 
-    # A Stainless API key, which you can generate on the Stainless organization dashboard
-    STAINLESS_API_KEY: $STAINLESS_API_KEY
-
-    # A GitLab token with permissions to read and write merge request comments.
-    GITLAB_TOKEN: $GITLAB_TOKEN
-
-preview:
-  extends: [.common, .preview]
-  only:
-    - merge_requests
-
-merge:
-  extends: [.common, .merge]
-  rules:
-    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
+    # Path to write a documented OpenAPI spec to. Optional; will only write if
+    # you code samples configured in your Stainless config.
+    DOCUMENTED_SPEC_PATH: YOUR_DOCUMENTED_SPEC_PATH

examples/merge_request_gitlab_generated.yml

@@ -1,6 +1,5 @@
 include:
-  - remote: "https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/preview/gitlab-ci.yml"
-  - remote: "https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/merge/gitlab-ci.yml"
+  - remote: "https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/build/gitlab-ci.yml"
   - remote: "https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/checkout-pr-ref/gitlab-ci.yml"
 
 .common:
@@ -28,26 +27,29 @@ include:
     # A GitLab token with permissions to read and write merge request comments.
     GITLAB_TOKEN: $GITLAB_TOKEN
 
-preview:
-  extends: [.common, .preview]
+build-sdk:
+  extends: [.common, .build-sdk]
   script:
     - apk add --no-cache git
-    - wget https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/dist/checkoutPRRef.js
 
-    - REF="base" node checkoutPRRef.js
-    # generate oas and save to OAS_PATH
-    # { insert your code here }
+    - |
+      if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ]; then
+        wget https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/dist/checkoutPRRef.js
 
-    - REF="head" node checkoutPRRef.js
-    # generate oas and save to OAS_PATH
-    # { insert your code here }
+        REF="base" node checkoutPRRef.js
+        # generate oas and save to OAS_PATH
+        # { insert your code here }
 
-    - wget https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/dist/preview.js
-    - node preview.js
+        REF="head" node checkoutPRRef.js
+        # generate oas and save to OAS_PATH
+        # { insert your code here }
+      else
+        # generate oas and save to OAS_PATH
+        # { insert your code here }
+      fi
+
+    - wget https://raw.githubusercontent.com/stainless-api/upload-openapi-spec-action/v1/dist/build.js
+    - node build.js
   only:
     - merge_requests
-
-merge:
-  extends: [.common, .merge]
-  rules:
-    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
+    - main

examples/prepare_combine.yml

@@ -47,7 +47,7 @@ jobs:
       # IMPORTANT: Always checkout the repository first!
       # Without this step, the action cannot access your spec files.
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Combine OpenAPI specs
         id: combine

examples/prepare_swagger.yml

@@ -28,7 +28,7 @@ jobs:
       # IMPORTANT: Always checkout the repository first!
       # Without this step, the action cannot access your spec files.
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           # Use the pull request head ref for PRs, otherwise use the default branch
           ref: ${{ github.head_ref || github.ref }}