Publishing Workflow

TIP

For most use cases, we recommend setting up the following workflows automatically by running speakeasy configure publishing in the root of your SDK repository and committing any generated files to your repo source. For a walkthrough of how this command works, please see this docs page.

Directly creating the workflow files below is only recommended for custom CI/CD workflows and users who are familiar with the Github Workflow syntax (opens in a new tab).

If you generate an SDK in pr mode, you can use the .github/workflows/sdk_publish.yaml workflow to publish it to package managers when the PR is merged into the main branch. The publishing workflow also creates a GitHub release for the new SDK version.

TIP

For most use cases we recommend setting up the following workflows automatically by running speakeasy configure publishing in the root of your SDK repository and comitting any generated files to your repo source. For a walk through of how this command works please see this docs page.

Directly creating the workflow files below is only reccommended for custom CI/CD workflows and users who are familiar with the Github Workflow syntax.

If you generate an SDK in pr mode, you can use the .github/workflows/sdk_publish.yaml workflow to publish it to package managers when the PR is merged into the main branch. The publishing workflow also creates a GitHub release for the new SDK version.

Here is an example of a publishing workflow file. It is agnostic to whichever langauge you may be generating your SDK in.

Advanced Publishing Config

You can use the reusable workflows included to publish the SDKs to package managers.

TypeScript

Set up a GitHub Actions secret with the name NPM_TOKEN and your npm token as the value.

Python

Set up a GitHub Actions secret with the name PYPI_TOKEN and your Python PyPI token as the value.

Java (Maven -- Sonatype Central Portal)

This section covers how to publish to the Sonatype Central Portal. For legacy OSSRH publishing support, see the next section.

To publish to Sonatype Central Portal, do the following:

• If you've never published to Maven before, set up a Sonatype Central Portal account. Follow the instructions here (opens in a new tab) to do so.
• You need a Sonatype-generated username and password for authentication. Click your username in the top right and select View Account -> Generate User Token.
  • Store the username and password as GitHub secrets.
• Create a Sonatype namespace. Follow the instructions here (opens in a new tab).
• You will need a GPG key to sign the artifacts. Follow the instructions here (opens in a new tab) to create one. An abbreviated guide is provided below.
  • Install GnuPG on your machine (for example, brew install gnupg)
  • Run gpg --gen-key. Note the key ID (for example, CA925CD6C9E8D064FF05B4728190C4130ABA0F98) and short ID (the last 8 characters of the key ID, for example, 0ABA0F98).
  • Run gpg --keyserver keys.openpgp.org --send-keys <your_keyId>.
  • Run gpg --export-secret-keys --armor <your_shortId> > secret_key.asc.
  • The secret_key.asc file will contain your GPG secret key.
• Add your GPG secret key and passphrase as GitHub secrets.
• Populate the secrets section of the workflow file with your secrets. Modify the values of secrets.<MY_SECRET_NAME> as needed in the following example:
  • ossrh_username: ${{ secrets.OSSRH_USERNAME }}
  • ossrh_password: ${{ secrets.OSSRH_PASSWORD }}
  • java_gpg_secret_key: ${{ secrets.GPG_SECRET_KEY }}
  • java_gpg_passphrase: ${{ secrets.GPG_PASSPHRASE }}
• In the workflow file, set the following:
  • publish_java: true
  • use_sonatype_central: true
• In the java section of gen.yaml, ensure the groupID you've provided matches your OSSRH org and the artifact name you want. For example:
  • groupID: com.example
  • artifactID: example-sdk
• In the java section of gen.yaml, provide the additional configuration required for publishing to Maven. Do not supply an ossrh_url. The below fields are required:
  • githubURL: github.com/org/repo
  • companyName: My Company
  • companyURL: https://www.mycompany.com
  • companyEmail: info@mycompany.com

Java (Maven -- Sonatype legacy OSSRH)

Java SDKs generated by the Speakeasy Generation Action are published to a Sonatype Open Source Software Repository Hosting (OSSRH) staging repository.

To publish your Java SDKs to OSSRH, you need to do the following:

• If you've never published to Maven before, set up an OSSRH staging repository by following the instructions in this getting started guide (opens in a new tab).
• You will need a GPG key to sign the artifacts. Follow the instructions in this GPG guide (opens in a new tab) to create one. What follows is an abbreviated guide to creating a GPG key.
  • Install GnuPG on your machine (for example, using brew install gnupg).
  • Run gpg --gen-key. Note the keyId (for example, CA925CD6C9E8D064FF05B4728190C4130ABA0F98) and shortId (the last 8 characters of the keyId, for example, 0ABA0F98).
  • Run gpg --keyserver keys.openpgp.org --send-keys <your_keyId>.
  • Run gpg --export-secret-keys --armor <your_shortId> > secret_key.asc.
  • secret_key.asc will contain your GPG secret key.
• Add your GPG secret key and passphrase as GitHub secrets.
• Add your OSSRH username and password as GitHub secrets.
• Populate the secrets section of the workflow file with your secrets. For example:
  • ossrh_username: ${{ secrets.OSSRH_USERNAME }}
  • ossrh_password: ${{ secrets.OSSRH_PASSWORD }}
  • java_gpg_secret_key: ${{ secrets.JAVA_GPG_SECRET_KEY }}
  • java_gpg_passphrase: ${{ secrets.JAVA_GPG_PASSPHRASE }}
• In the workflow file, set publish_java: true.
• In the java section of gen.yaml, ensure the groupId you've provided matches your OSSRH org and the artifact name you want. For example:
  • groupID: com.example
  • artifactID: example-sdk
• In the java section of gen.yaml, provide the additional configuration required for publishing to Maven. The below fields are required:
  • ossrhURL: https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/
  • githubURL: github.com/org/repo
  • companyName: My Company
  • companyURL: https://www.mycompany.com
  • companyEmail: info@mycompany.com

C# (NuGet)

C# SDKs generated by Speakeasy are published to NuGet.

To publish your C# SDKs to NuGet, you need to do the following:

• Create a NuGet (opens in a new tab) account.
• You will need a NuGet API key to publish to NuGet. When creating your NuGet API key:
  • Set the Package Owner field to the user or organization that will "own" your SDK artifact.
  • Ensure that the API key has the relevant Push scoped (if the package already exists, the API key may not need "Push new packages and package versions" permissions).
  • Populate the Glob Pattern and Available Packages fields in a way that will permit publishing your SDK (use the packageName specified in gen.yaml).
• Set a GitHub Actions secret named NUGET_API_KEY with your API key as its value.
• Populate the secrets section of the workflow with nuget_api_key: ${{ secrets.NUGET_API_KEY }}.
• In the generation.yaml file, add publish_csharp: true to the with section.
• If you're generating SDKs in pr mode, add publish_csharp: true to the with section of the publish.yaml file.
• In the csharp section of gen.yaml, ensure the packageName you've provided matches the package name you want to publish. This can be a dot-separated name, which will set the NuGet ID and file tree structure accordingly. For example: packageName: Company.Product.Feature will yeild a file structure as follows:

This is accordance with the Microsoft design guidelines for NuGet packages. (opens in a new tab)