Sourced*

Migration

Import a Stainless project from GitHub without hunting for files

· 3 min read · Sourced

  • stainless
  • github
  • migration
  • openapi
  • sdk

The fastest Stainless migration is not "find the right GitHub URL, paste it into a form, then guess which files matter." The fastest path is: connect GitHub, choose the repository, let the migration tool find openapi.yaml and stainless.yml, then preview the replacement docs and SDKs before anything changes.

That is the workflow Sourced is building around repo import. It is designed for the searches people make when they are trying to leave a generator safely:

  • "How do I migrate off Stainless?"
  • "Where is my stainless.yml used?"
  • "Can I import an OpenAPI repo from GitHub?"
  • "How do I generate SDKs from a GitHub repo?"
  • "Can I preview docs before changing my docs domain?"

What a one-click GitHub import should do

A real import should do five things:

  1. Connect to GitHub with the narrowest app permissions possible. The app should ask for repository access, not personal account sprawl.
  2. Let you pick the repo in GitHub. You should not need to copy the URL first.
  3. Detect the source files. Common paths include openapi.yaml, openapi.yml, openapi.json, docs/openapi.yaml, stainless.yml, and stainless.yaml.
  4. Show the detected contract before generation. The user should see which spec, branch, docs root, and config file will be used.
  5. Generate previews only. A first import should not publish to npm, PyPI, GitHub, or a docs domain.

The important UX detail is sequence. Users want to connect GitHub first, then choose. Asking for a URL before connection makes the migration feel like work before trust exists.

Why stainless.yml matters

stainless.yml is not just decoration. For teams already using Stainless, it usually contains the migration intent:

  • package names
  • resource grouping
  • method naming preferences
  • auth conventions
  • docs settings
  • publish targets

OpenAPI tells the generator what the API is. The Stainless config often tells the generator how the company wants customers to experience it. A migration that ignores the config may still produce an SDK, but it risks changing import paths, method names, and examples.

Sourced reads OpenAPI plus the Stainless config as a migration contract, then produces a report before publishing. The target is not "generate something new." The target is "preserve the SDK experience customers already use, then improve the release workflow around it."

What happens after import

After GitHub import, the safe order is:

  1. Parse OpenAPI and stainless.yml.
  2. Generate TypeScript and Python SDK previews.
  3. Generate a hosted noindex docs review site.
  4. Produce a compatibility report against the current SDK surface.
  5. Show release readiness for GitHub, npm, PyPI, docs domain, redirects, sitemap, and llms.txt.
  6. Wait for explicit approval before any external write.

Free should mean enough to evaluate the migration. In Sourced, that means unlimited previews and up to 2 hosted noindex docs review sites before a credit card. Production custom domains, registry publishing, repo sync, team controls, and longer retention are the upgrade path.

What to check before approving the migration

Before you approve a publish or docs cutover, check:

  • Do generated method names match the current SDK?
  • Do package names and imports match the current docs?
  • Does auth use the same environment variables customers already know?
  • Are generated docs routes acceptable, or do redirects need to be added?
  • Does the compatibility report call out any missing endpoints?
  • Are npm and PyPI configured through trusted publishing instead of long-lived tokens?
  • Is the preview docs site noindex until the custom domain is approved?

If any answer is unclear, do not publish. The whole point of a migration workflow is to surface these problems while the old docs and SDKs are still live.

How this compares to past migrations

The old way to migrate from Stainless was mostly manual:

  • find OpenAPI
  • find stainless.yml
  • run a generator
  • compare SDK methods by hand
  • rebuild docs
  • wire publishing
  • hope nothing changed for customers

The better way is a preview-first import. GitHub is the file picker, OpenAPI is the source of truth, stainless.yml preserves intent, and the release report becomes the checklist.

Start the Stainless migration or compare Sourced vs Stainless.