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.
name: Publish"on": push: branches: - main paths: - RELEASES.mdjobs: publish: uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-publish.yaml@v15 secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
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.
name: Publish"on": push: branches: - main paths: - RELEASES.mdjobs: publish: uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-publish.yaml@v15 secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }} npm_token: ${{ secrets.NPM_TOKEN }}
Python
Set up a GitHub Actions secret with the name PYPI_TOKEN
and your Python PyPI token as the value.
name: Publish"on": push: branches: - main paths: - RELEASES.mdjobs: publish: uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-publish.yaml@v15 secrets: github_access_token: ${{ secrets.GITHUB_TOKEN }} speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }} npm_token: ${{ secrets.PYPI_TOKEN }}
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.
- Install GnuPG on your machine (for example,
- Add your GPG secret key and passphrase as GitHub secrets.
- Populate the
secrets
section of the workflow file with your secrets. Modify the values ofsecrets.<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 ofgen.yaml
, ensure thegroupID
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 ofgen.yaml
, provide the additional configuration required for publishing to Maven. Do not supply anossrh_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.
- Install GnuPG on your machine (for example, using
- 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 ofgen.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 ofgen.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
andAvailable Packages
fields in a way that will permit publishing your SDK (use thepackageName
specified ingen.yaml
).
- Set the
- Set a GitHub Actions secret named
NUGET_API_KEY
with your API key as its value. - Populate the
secrets
section of the workflow withnuget_api_key: ${{ secrets.NUGET_API_KEY }}
. - In the
generation.yaml
file, addpublish_csharp: true
to thewith
section. - If you're generating SDKs in
pr
mode, addpublish_csharp: true
to thewith
section of thepublish.yaml
file. - In the
csharp
section ofgen.yaml
, ensure thepackageName
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:
Company/ Product/ Feature/ Models/ <SDKClassName>.cs ...
This is accordance with the Microsoft design guidelines for NuGet packages. (opens in a new tab)