feat: add preview support for generating oas (#74)

* feat: add preview support for generating oas

* use same action for checking out head

* test

* test

Author: cjquines

README.md

@@ -96,7 +96,7 @@ and integration with docs platforms, see the [examples directory](./examples).
 
 ## Actions
 
-This repository provides three GitHub actions.
+This repository provides four GitHub actions.
 
 - `stainless-api/upload-openapi-spec-action/build`: Build SDKs for a Stainless
 project. This action is also usable in GitLab CI. For information about the
@@ -110,6 +110,11 @@ the [action definition](./preview/action.yml).
 a pull request. For information about the input parameters, see the [action
 definition](./merge/action.yml).
 
+- `stainless-api/upload-openapi-spec-action/checkout-pr-ref`: Checkout the base
+or head commit for previewing a pull request's changes, saving changes to the
+config when needed. For information about the input parameters, see the [action
+definition](./checkout-pr-ref/action.yml).
+
 ### Workflow permissions
 
 The GitHub actions use the following
@@ -120,14 +125,14 @@ will comment on the pull request with the build results. This is set to true by
 default. The actions use the `github_token` input to make a comment, and the
 comment must have the `pull-requests: write` permission.
 
-- The `preview` action relies on being in a Git repository that can fetch from
-the remote to determine base revisions. This will be the case if you use the
-[`actions/checkout`](https://github.com/actions/checkout) GitHub action
-beforehand. That action needs the `contents: read` permission.
+- The `preview` and `checkout-pr-ref` actions rely on being in a Git repository
+that can fetch from the remote to determine base revisions. This will be the
+case if you use the [`actions/checkout`](https://github.com/actions/checkout)
+GitHub action beforehand. That action needs the `contents: read` permission.
 
 ### Versioning policy
 
-This action uses [semantic versioning](https://semver.org/), and you can pin
+These actions use [semantic versioning](https://semver.org/), and you can pin
 your action to a major (`v1`), minor (`v1.0`), or patch (`v1.0.0`) version.
 The public API includes:
 

checkout-pr-ref/action.yml

@@ -0,0 +1,32 @@
+name: Stainless — Checkout PR ref
+description: Git checkout the base or head of a pull request
+runs:
+  using: node20
+  main: ../dist/checkoutPRRef.js
+inputs:
+  ref:
+    description: >-
+      Which ref to checkout. Options: 'base', 'head'.
+    required: true
+  oas_path:
+    description: Path to your OpenAPI spec.
+    required: true
+  config_path:
+    description: >-
+      Path to your Stainless config. Optional; only provide this if you are
+      building or maintaining the ground truth Stainless config in your own
+      repo.
+    required: false
+
+  # We think it's unlikely you'll need to use non-default inputs for these:
+  base_sha:
+    description: >-
+      The base SHA for the pull request. Used to create a base build.
+    required: false
+    default: ${{ github.event.pull_request.base.sha }}
+  head_sha:
+    description: >-
+      The head SHA for the pull request. Used to get the OpenAPI spec and
+      Stainless config for the preview build.
+    required: false
+    default: ${{ github.event.pull_request.head.sha }}