Publish your SDKs

Once you are satisfied with the structure and naming conventions of your SDK, you can distribute them to end users by publishing them to package registries (for example, npm, PyPI, and maven). After a one-time setup, future Stainless SDKs flow from our private preview repository to your GitHub organization where they're picked up by the package registries.

The Stainless managed release flow handles versioning and changelogs expected in quality SDKs. You can even automate this process so subsequent changes to your OpenAPI spec trigger new SDK releases.

Identify or create your GitHub repositories

When getting started, we generate SDKs into private preview repositories under stainless-sdks. But your users expect them to be found in repos within your GitHub organization.

If you do not have a repository yet, you need to create one.

Be sure to select the correct organization as the owner and set a name that meaningfully identifies your SDK—for example, my-<brand>-python is a common choice for Python SDKs.

The repository can be public or private.

info

You need one GitHub repo for each SDK (one for Node, one for Python, and so on).

Install the Stainless GitHub App

The Stainless GitHub App does the work of pushing preview SDKs to your repos. To install it:

1. Navigate to the correct project in the Stainless dashboard.
2. For one of your target languages, click Edit > Install GitHub App. (It does not matter from which language you trigger this process.)
3. Follow the installation flow. When prompted, select which repositories the Stainless GitHub App can access.
4. Once repositories have been selected and permissions have been reviewed, click Install & Authorize.

warning

By default All repositories is selected, but we recommend you only select the repositories you plan to use for Stainless SDKs.

Connect package registries

Package registries make your packages readily available to your users. Once configured, Stainless automatically updates package registries on releases, but you have to complete a one-time setup and give Stainless permissions to update your packages on your behalf.

Node/TypeScript: npm

Get an Automation API token

1. Log in or sign up at npm.
2. Click on your profile picture on the top right to access a dropdown and then navigate to Access Tokens > Generate New Token.
3. Choose a token version:
   • Granular Access Token, recommended if you’re publishing the SDK under a scope (for example, @<your-company-name>/sdk)
   • Classic Token, required if not publishing under a scope
4. If creating a Classic Token, ensure you have selected Automation as the token type. Apart from that, the token settings you choose are up to you.

Add the API token to your Node GitHub repository

1. Navigate to the actions secrets for your repository at Secrets and variables > Actions > New repository secret, the URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add a new secret named NPM_TOKEN with your API token from the Get an Automation API token step.

Choose a package name and update the Stainless dashboard

1. You have to choose an available name in the registry. Suggested names are:

   • <your-company-name>
   • @<your-company-name>/sdk (This requires you have the right npm organization.)

   You can check if the name is available.

2. Update the Stainless dashboard with your package name. The SDK generation process restarts and pushes to NPM once it is done.

Python: PyPI

Get an API token

1. Log in or sign up at PyPI.
2. Navigate to your account settings.
3. Scroll down to the API tokens section and click Add API Token. You may have to verify your email address and set up 2FA if you haven't done so already.

Add the API token to your Python GitHub repository

1. Navigate to the actions secrets for your repository at Secrets and variables > Actions > New repository secret, the URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add a new secret named PYPI_TOKEN with your API token from the Get an API token step.

Choose a package name and update the Stainless dashboard

1. You have to choose an available name in the registry. Suggested names are:

   • <your-company-name>
   • <your-company-name>-client

   You can check whether the name is available by testing the link at https://pypi.org/project/<your-package-name>. If it is available, PyPI should say that the package is not available.

2. Update the Stainless dashboard with your package name. The SDK generation process restarts and pushes to PyPI once it is done.

Java & Kotlin: Sonatype Maven Central

We publish JVM packages to Sonatype.

warning

Setting up Sonatype can be an involved process. We recommend you go through this process after getting your SDKs into a satisfactory state.

Create a Sonatype Jira ticket

1. Make an account on Sonatype Jira

   You’ll likely want to use a group email address (for example, dev@ or sdks@) and put the password in your shared password manager, rather than tie the account to one individual. This is the account that owns your published SDKs and it’s a bit tricky to move ownership later.

2. Create a one-time package setup ticket

   

   • This is to create the Sonatype repositories and permissions used to publish the package to Maven Central. This request should not be made until we have a public GitHub repo for the package, because the Sonatype team may manually review the metadata in the source code before approving the package.
   • The summary and description can just mention that you are creating a new project and its name.
   • Group Id, most likely your reverse domain (for example, com.mycompanyname).
   • Project URL and SCM url should be the location of the Java SDKs on GitHub.
   • Username, include both stainless-dev and your username on Sonatype Jira. (This allows us to push and publish changes on your behalf.)
   • Already synced to central, almost certainly “No”, unless you are migrating a pre-existing Java SDK to Stainless.

Prove ownership over your domain

Add a temporary TXT record to the DNS for your primary domain (the reverse of your groupId) to verify that the person registering this Java group actually controls the domain.

The contents of the TXT record is the ID of the JIRA ticket created in the previous step (for example, OSSRH-12345).

Set up PGP package signing

1. Install GnuPG.

2. In a terminal, run gpg --gen-key. You are prompted to enter your name, email, and a passphrase for the keypair.

3. Run gpg --list-keys --keyid-format short:

   % gpg --list-keys --keyid-format short
   [keyboxd]
   ---------
   pub   ed25519/7FAD9FAA 2023-08-02 [SC] [expires: 2026-08-01]
         418D41921938A753CAAE57985114AD037FAD9FAA
   uid         [ultimate] Your Organization <you@yourorg.com>
   sub   cv25519/07EB38A7 2023-08-02 [E] [expires: 2026-08-01]

4. Export the key in ASCII-armored format (7FAD9FAA is the short key ID in this example).

   $ gpg --export-secret-keys --armor 7FAD9FAA
   -----BEGIN PGP PRIVATE KEY BLOCK-----
   
   lIYEZMpnEhYJKwYBBAHaRw8BAQdA1FQMKz+wwliKNdLehegZP0QiaKrZJqADNyVn
   VCUzIrD+BwMCwZrqVbVPfSr8NwxEh3M6kWtMGmnLMOk/NWVe7dtCxDxo37l/Ncxj
   Mm9EZiH6WXwoXXq20nOW354oNOVz/UPvDU+oaRDDUM9SYs392i69WLQjWW91ciBP
   cmdhbml6YXRpb24gPHlvdUB5b3Vyb3JnLmNvbT6ImQQTFgoAQRYhBEGNQZIZOKdT
   yq5XmFEUrQN/rZ+qBQJkymcSAhsDBQkFo5qABQsJCAcCAiICBhUKCQgLAgQWAgMB
   Ah4HAheAAAoJEFEUrQN/rZ+qgtsBAMCBuTqYEJljxStRO7SsMLWOc47CIIXD0Yid
   CbySBX0ZAP9DXuuGVYbHFONvHxNKszu2hY9A1BbRuNjeGeWuVOw9ApyLBGTKZxIS
   CisGAQQBl1UBBQEBB0AFxkZ+ZdEN7Epwri/w5ETAf+MOqdwAP2sS6TccSjEiXQMB
   CAf+BwMCtKG1TBUSC/z8tn761I5j+ifVIuMqdQPYIhZtjvIyC+NyrBi0j1ZtUG4A
   DAeDKNyM63uyb7omOH8+Lu0J71SGhVnZWszUOf3rrT/TA5MktYh+BBgWCgAmFiEE
   QY1Bkhk4p1PKrleYURStA3+tn6oFAmTKZxICGwwFCQWjmoAACgkQURStA3+tn6qa
   XAD/W2ucVURngmCUiUtdjQAZz36yQYPQmBhcdabZMyXKHz0A/itwYkuRbD2mp4p/
   xJk/QLXs/2/xBA6s0ROVVspy6MEA
   =p/g/
   -----END PGP PRIVATE KEY BLOCK-----

Add Sonatype credentials and PGP secret key to Java/Kotlin GitHub repository

• In your GitHub repository, navigate to Settings > Secrets and Variables > Actions.
• Click New Repository Secret.

• Set Name to {MY_ORG}_SONATYPE_GPG_SIGNING_KEY (replace {MY_ORG} with your organization name).
• In Secret, paste the PGP private key block from gpg --export-secret-keys --armor <keyid>.
• Click Add Secret.

• Following the same process, add these secrets:

  {MY_ORG}_SONATYPE_GPG_SIGNING_PASSWORD

  • The passphrase you entered when creating the keypair.

  {MY_ORG}_SONATYPE_USERNAME

  {MY_ORG}_SONATYPE_PASSWORD

  • Your username and password for your Sonatype account.

Go: GitHub

Go installs packages from source, so nothing other than the GitHub repository is required for setup. We automatically request updates from the Go package index which updates your godoc on a release.

Versioning and releases

Whenever we generate a new change for your SDK, we create and merge a PR into the next branch in your production repository. Each commit should describe the related change using the Conventional Commits format.

A Release PR is then created against the main branch, which collects individual changes until you are ready to release them. The PR waits for a code owner's review and merges automatically upon approval.

Your first release will be Release 0.1.0-alpha.1, meaning that the first release published to your package manager will have an alpha tag.

Stainless will increment the version used in each subsequent release PR based on the prior one. We use the semantic information of the commits in the release to find the next available version:

• Breaking changes increment the major version number (if and only if the version is already at least 1.0.0)
• Features increment the minor version number
• Fixes increment the patch number

You can override our suggested version by modifying the PR title. Doing so will propagate your provided version (including any alpha or beta tags) to the release in Github and your package manager. We recommend:

• Staying in the alpha or beta stage while your SDKs still have diagnostic errors
• Staying in the 0.0.x range while your SDKs still have diagnostic warnings
• Staying in the 0.x.y range while your SDKs still have unacknowledged diagnostic notes
• Moving to 1.0.0 once your SDK has none of the above