Publish SDKs
Prerequisites
- The Speakeasy CLI
- Speakeasy generated SDKs
- Access tokens or credentials for target package managers
Supported Package Managers
Language | Package Manager | Prerequisites | Notes |
---|---|---|---|
TypeScript | npm | Access tokens (opens in a new tab) | Create an access token of type Automation . |
Python | PyPI | API tokens (opens in a new tab) | |
Go | GitHub | Repo visibility (opens in a new tab) | For private repos, add the Speakeasy app (opens in a new tab). |
Java | Maven | Get started with Maven Central (opens in a new tab) and verify domain ownership (opens in a new tab) | |
PHP | Packagist | See publishing packages (opens in a new tab) | Monorepo setups not permitted. |
C# | NuGet | API key (opens in a new tab) | |
Terraform | Terraform | GPG Key (opens in a new tab) |
Naming Packages
Language | Package Manager | Example Package | Naming Conventions |
---|---|---|---|
TypeScript | npm | @npm-org/package-name | Lower case, hyphen separated |
Python | PyPI | package_name | Lower case, underscore separated |
Go | GitHub | github.com/org/repo-name | Lower case, hyphen separated |
Java | Maven | packageName | Camel case |
PHP | Packagist | org/package-name | Lower case, hyphen separated |
C# | NuGet | PackageName | Pascal case, period separated |
Terraform | Terraform | terraform-provider-name | Lower case, hyphen separated |
TIP
For global package managers like PyPI and Maven, ensure the package name is unique.
Publishing Packages
1. Start Publishing Configuration
speakeasy configure publishing
Select the existing SDK targets to configure publishing. If no SDK targets are available, run speakeasy configure targets
first.
2. Provide Publishing Credentials
Default input environment variables for publishing are provided.
3. Verify Configuration Files
Once configuration is complete, the following files will be generated or updated:
.speakeasy/workflow.yaml
– Speakeasy workflow configuration..github/workflows/sdk_generation.yaml
– GitHub Action to generate SDKs..github/workflows/sdk_publish.yaml
– GitHub Action to publish SDKs.
4. Set Up Repository Secrets
- Navigate to GitHub repository Settings > Secrets & Variables > Actions.
- Click New repository secret.
- Add
SPEAKEASY_API_KEY
(if needed) and any other required tokens (e.g.,NPM_TOKEN
).
5. Push Changes and Verify
Commit and push the updated workflow files. Once your generated SDK is pushed to github, you can manually kick of publishing for your first version.
6. Complete Language Specific Configuration
Java and C# require additional setup after running speakeasy configure publishing
.
Java Maven: Sonatype Central Portal (Recommended)
For legacy OSSRH publishing support, see the next section.
- Create a Sonatype Central Portal account (opens in a new tab) (if needed).
- Generate a Sonatype username and password for authentication (opens in a new tab). Save these for step 5.
- Create a Sonatype namespace (opens in a new tab).
- Create a GPG key to sign the artifacts (opens in a new tab). Save these for step 5.
- Install GnuPG:
brew install gnupg
- Generate a key:
gpg --gen-key
. Note the key ID (e.g.,CA925CD6C9E8D064FF05B4728190C4130ABA0F98
) and short ID (e.g.,0ABA0F98
). - Send the key:
gpg --keyserver keys.openpgp.org --send-keys <your_keyId>
- Export the secret key:
gpg --export-secret-keys --armor <your_shortId> > secret_key.asc
- The file
secret_key.asc
will contain the GPG secret key.
- Install GnuPG:
- Store the following secrets Github actions secrets:
OSSRH_USERNAME
OSSRH_PASSWORD
GPG_SECRET_KEY
GPG_PASSPHRASE
- In the java section of
gen.yaml
, provide the additional configuration required for publishing to Maven:
java: #ensure the `groupID` matches the OSSRH org groupID: com.example #ensure the `artificatID` matches the artifact name: artifactID: example-sdk githubURL: github.com/org/repo companyName: My Company companyURL: https://www.mycompany.com companyEmail: info@mycompany.com
Java Maven: Sonatype legacy OSSRH
- Create an OSSRH staging repository (opens in a new tab).
- Create a GPG key to sign the artifacts (opens in a new tab). Save these for step 3.
- Install GnuPG:
brew install gnupg
- Generate a key:
gpg --gen-key
. Note the key ID (e.g.,CA925CD6C9E8D064FF05B4728190C4130ABA0F98
) and short ID (e.g.,0ABA0F98
). - Send the key:
gpg --keyserver keys.openpgp.org --send-keys <your_keyId>
- Export the secret key:
gpg --export-secret-keys --armor <your_shortId> > secret_key.asc
- The file
secret_key.asc
will contain the GPG secret key.
- Install GnuPG:
- Store the following secrets Github actions secrets:
OSSRH_USERNAME
OSSRH_PASSWORD
GPG_SECRET_KEY
GPG_PASSPHRASE
- In the Speakeasy workflow file (opens in a new tab), add
useSonatypeLegacy: true
:
workflowVersion: 1.0.0speakeasyVersion: latestsources: my_source.yaml: inputs: - location: my_source.yamltargets: java: target: java source: my_source.yaml publish: java: #add useSonatypeLegacy: true useSonatypeLegacy: true ossrhUsername: test ossrhPassword: $ossrh_password gpgSecretKey: $java_gpg_secret_key gpgPassPhrase: $java_gpg_passphrase
- In the java section of
gen.yaml
, provide the additional configuration required for publishing to Sonatype legacy:
java: #ensure the `groupID` matches the OSSRH org groupID: com.example #ensure the `artificatID` matches the artifact name: artifactID: example-sdk 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
- Create a NuGet (opens in a new tab) account.
- Create a NuGet API key:
- Set the Package Owner field to the user or organization that will "own" the SDK artifact.
- Ensure the API key has the relevant Push scope. 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 allows publishing the SDK. Use the
packageName
specified in thegen.yaml
file.
- Store the
NUGET_API_KEY
in the GitHub Actions secrets. - In the C# section of
gen.yaml
add:csharp:packageName: MyPackageName # Ensure this matches the desired NuGet package IDpackageTags: sdk api client # Provide space-separated tags for searching on NuGetenableSourceLink: true # Enables publishing with Source Link for better debuggingincludeDebugSymbols: true # Includes .pdb files for publishing a symbol package (.snupkg) - In the
info
section of the OpenAPI document, describe what the package is for in thedescription
property. It will be set as the Package description (opens in a new tab), visible when searching for the package on NuGet.openapi: 3.1.0info:description: This description will be visible when searching for the package on NuGet. - In the
externalDocs
section of the OpenAPI document, provide the website's homepage in theurl
property. It will be set as the Project URL (opens in a new tab), visible in the package's "About" section.openapi: 3.1.0externalDocs:url: https://homepage.com/docsdescription: Public Docs - In the root of the repository:
- Add a
LICENSE[.md|.txt]
file (see Licensing (opens in a new tab) for more details). - Add a 128x128 dimension image file called
icon[.jpg|.png]
to display on the NuGet package page. - Review the
NUGET.md
file, which is similar to the mainREADME.md
but excludes theSDK Installation
andAvailable Operations
sections. For more details, see Editing Your SDK Docs.
- Add a
PHP
- Create a Packagist (opens in a new tab) account (if needed).
- Generate a Safe API Token:
- Navigate to Packagist Profile (opens in a new tab) and log in.
- Record the "Safe API Token" under account settings.
- Update GitHub Action Secrets with Packagist credentials:
- Navigate to repository's Github Secret Settings.
- Update the following secrets:
PACKAGIST_TOKEN
: Set this to the Safe API Token from step 2.PACKAGIST_USERNAME
: Set this to Packagist username.
- Store the following secrets in the GitHub Actions secrets:
PACKAGIST_TOKEN
PACKAGIST_USERNAME
- Confirm that the publishing job is properly set up with the updated credentials.
Publishing in the Speakeasy Dashboard
The SDK publishing tab in the Speakeasy dashboard provides an overview of the publishing history and offers various utilities for setting up and maintaining SDK publishing.
If package manager secrets were not set during the initial SDK repo setup, the publishing dashboard provides an interface to attach these secrets to the repository.
For GitHub actions set up with mode:pr
, the publishing dashboard highlights open PRs in the SDK repo that are pending release. This view displays the exact SDK version that will be published upon merging the PR.