chore(ci): setup automated stainless builds

[dgellow]

What does this PR do?

This pull request adds a new workflow that does 2 things:

1. generate SDK preview builds whenever the OpenAPI spec file is modified in a PR
2. on PR merge, generate SDK builds that will be pushed to the different SDK repos (i.e start the release process)

Note

No repo secret STAINLESS_API_KEY is needed, the authentication is done automatically via GitHub OIDC.

Test Plan

I tested in my fork: stainless-api#3

[leseb]

Just added the STAINLESS_API_KEY key to the repo :)

[leseb]

I just realized that this can only work when NOT submitting a PR from fork given Github security model on passing secrets to workflow.

@dgellow I'm wondering how this is used elsewhere in practice and how other projects overcome that? Thanks!

[dgellow]

I'm moving this one back to draft until I have a great documented solution to share

[bbrowning]

Parts 1, 2, 3, and 4 of https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/ are important reading if we need to find a way to pass a secret into something triggered on every pull request.

[dgellow]

Thanks @bbrowning. I actually already read those articles, unfortunately there are a few details that are making the mentioned solutions a no-go for this repo.
However I have a great solution that won't require any CI secret. I expect to have it ready later today and will move the PR out of draft asap :)

edit: well, not exactly today, my plane internet is spotty

[dgellow]

Currently blocked by stainless-api/upload-openapi-spec-action#133. Once merged I will update the github action SHA and that should be ready.

[dgellow]

Some notes that may be of interest that I shared on Discord.

The workflow

1. external contributor (EC) forks the repo
2. EC does some modifications to the Stainless config file or your spec file
3. EC opens a PR
4. the CI workflow is triggered, run the github action
5. action creates a new preview branch for your Stainless project, uploads the config + spec file
6. action starts a build (meaning all sdks configured in your config file will be generated + pushed to an internal repo)
7. action wait for the build to complete
8. action reports any build diagnostics as github comment to the PR
9. when the PR is merged, the action start a new build but this time for your main branch, which will be pushed to your public SDK repos

On security

• instead of a static API key in a repo secret the github action will be using github OpenID Connect (OIDC)
  • in short, github mints a short lived token that cannot be tempered with (cryptographically signed)
• the token includes info regarding the repository, that makes it possible to validate you're actually allowed to push to the Stainless project. The only requirement is to have our github app installed in your github org (it does not need to be given read or write access to the repo where you generate your spec)
• to support PRs from forks the workflow needs to rely on the github event pull_request_target , followed by a git checkout to the PR branch
• workflow files aren't at risk, in the case of a fork PR the workflows from the base repo are used. Github will never run workflows maliciously edited by a fork, unless they have been merged
• the github action doesn't evaluate anything from the fork repo, it only read the spec + config file then interact with the Stainless API

[dgellow]

I'm not too sure where exactly you would prefer that file to be located 🤔. I used docs/static/ to keep it close to the spec file, but that's really up to you

[ashwinb]

@dgellow I think we should keep it in the client-sdks/stainless/ folder. There is already an openapi.yml there. We can keep a stainless-config.yml right next to it. The README there can mention that this file is named openapi.stainless.yml in the stainless-sdk/ repository.

[ashwinb]

@dgellow how could we do a test-run of this? We have a change from @raghotham which updated the types. See #3948