End-to-end SDK generation and publishing with GitHub Actions
This tutorial includes the following SDK languages and versions:
TypeScript v1 TypeScript v2 Java Python v1 Python v2 C# Go PHP ✅ ✅1 ✅ ✅1 ✅ ✅ ✅ ❌ 1 By default the control repo template mentioned below creates a config file for TypeScript v1 and Python v2 SDK generation. To use TypeScript v2 or Python v1, ensure the
liblabVersion
in thelanguageOptions
section for the relevant language is set as required.
One of the most useful offerings of liblab is the ability to automate SDK creation and publishing. At liblab, we believe in total code ownership and the ability to control the entire SDK lifecycle. This means that you can use liblab to generate SDKs and then use your own CI/CD pipeline to publish them to your own private or public repositories. We emphasize that you should be able to control the entire SDK lifecycle, and we provide the tools to do so.
This tutorial shows you how to use GitHub Actions with liblab to automate the SDK generation and publishing process. This will take you from an API spec file all the way to an SDK published to the relevant public package manager, such as npm, PyPI, NuGet or Go Packages.
End goal
This is the end-to-end process that you will set up in this tutorial:
Video walkthrough
You can find a video walkthrough of this tutorial on the liblab YouTube channel:
Prerequisites
To compete this tutorial you will need:
- The liblab CLI installed and logged in
- An API spec
- A GitHub account, with the permissions to create new repositories, Actions secrets, and fine-grained access tokens in your GitHub organization, or in your personal account
- An account with the relevant package manager, such as npm, PyPI or NuGet, with publishing permissions
Steps
In this tutorial you will:
- Create a control repo for your API spec and liblab config file
- Create SDK repos for each SDK language you want to publish
- Create liblab and GitHub tokens
- Create package manager tokens
- Update your spec and config file
- Merge SDK PRs
- Create a release in GitHub
- Verify the publish
1. Create a control repo
The central driver of the liblab CI/CD workflow is a control repo, a repository that contains your liblab config file, any hooks code, and optionally your API spec file. This repo is the source of truth for your SDKs and documentation.
liblab provides a template repo that you can use to get started.
-
Select the button below to create a new control repo using this template.
-
Give your new control repository a name, a description, and make it public or private.
-
Select Create repository to create the repository from the template.
The repository that is created has:
- An example liblab config file
- An API spec for the Swagger Petstore
- A GitHub Action to create PRs for your SDKs when your API spec or config file changes
- A GitHub Action that polls for liblab updates and creates PRs for your SDKs when there is a liblab update
You can read more about the control repo in the control repo documentation.
This is what you should have so far:
2. Create SDK repos
Your generated SDKs live in separate repos - one per SDK language. These repos need to be created before you can publish your SDKs.
liblab provides template repos for these SDK repos that you can use to get started.
-
Select the relevant buttons below to create repos from the different templates:
-
For each repo you create, give your new SDK repository a name, a description, and make it public or private.
-
Select Create repository to create the repository from the template.
The repository that is created has:
- A GitHub Action to publish the SDK to the relevant package manager
-
Repeat this process for each SDK language you want to publish.
You can read more about the SDK repos in the SDK repos documentation.
This is what you should have so far:
3. Create liblab and GitHub tokens
The GitHub Actions that create SDKs need 2 secrets set - a liblab token that authenticates the liblab CLI, and allows it to run as you, and a GitHub token that allows the liblab CLI to push to your SDK repos.
Create a liblab token
-
From the liblab CLI, run the following command to generate a liblab token:
Terminalliblab token create GITHUB_PR_TOKEN
You can replace
GITHUB_PR_TOKEN
with any name you choose for the token. If you have multiple APIs that you are generating SDKs for, you can either share the token between them, or create different tokens for each API.TerminalToken successfully generated, it will be valid for 90 days
-TOKEN-----------------------------------------
liblab_WoVBcuKKvwIGw2-EBjGHRjJdAJ46qggy8caFiqSP
-----------------------------------------------noteBy default this token will expire after 90 days. You can increase this to up to 364 days by passing the
--durationInDays
parameter.You can read more on the
liblab token
command in the CLI documentation. -
Copy the token that is generated. You need the string between the
-TOKEN-
and-------
lines, not those lines themselves. -
Add this new token to your Github Control Repo's Actions secrets as
LIBLAB_TOKEN
.This token will be used to interact with liblab during each Action run. You can find the documentation on how to do this in the Github secrets documentation.
Create a GitHub token
For the Action in your control repo to push to your SDK repos, you will need to generate a GitHub Fine Grained Access Token that has access to write to your SDK repos.
-
From GitHub, select your profile picture, then select Settings, Developer settings, Personal access tokens, then Fine-grained tokens.
-
Give the token a name and a description
-
Set the expiration for the token based on your needs or your organizations security policies.
tipIt's helpful to create a reminder for yourself such as a calendar item to refresh the token just before it expires!
-
Select the repositories that this token will have access too. It is good practice to limit the scope of these tokens, so select just the SDK repositories that you want to publish to.
-
Set the token permissions. This token will need the following permissions:
Permission Access Commit Statuses Read/Write Contents Read/Write Metadata Read Pull Requests Read/Write Workflows Read/Write When you set these permissions, you will see the following:
-
Add this token to your control repo GitHub Action secrets as
LIBLAB_GITHUB_TOKEN
.
This is what you should have so far:
4. Create package manager tokens
Depending on what SDK language you are using, you will need to create additional secrets.
- TypeScript
- Python
- C#
- Java
- Go
To publish to npm, you will need an npm access token. You can generate a new access token from your user settings on npm.
-
Select the Access Tokens tab, drop down the Generate New Token button, then select Granular Access Token.
-
Fill in all the required details for the token such as the name and expiry.
-
Make sure that this token has read and write permission to publish packages. If the package already exists, you can scope this token to just that package, otherwise this token needs read and write for all packages.
-
Once the token has been created, make a copy of it.
-
In your TypeScript SDK repo, add this token as an Actions secret named
NPM_TOKEN
.
You can learn more about creating npm tokens in the npm access tokens documentation.
To publish to PyPI you will need an API token. You can generate a new API token from your account settings page on PyPI.
-
Select Account settings, scroll to the API tokens section, then select the Add API token button.
-
Give the token a name.
-
Select the scope for the token. If the package already exists, select that package for the scope, otherwise select Entire account (all packages).
-
Select the Create token button.
-
Once the token has been created, make a copy of it.
-
In your Python SDK repo, add this token as an Actions secret named
PYPI_TOKEN
.
You can learn more about creating PyPI tokens in the PyPI API tokens documentation.
To publish to NuGet, you will need a NuGet API key. You can generate an API key from your account on NuGet.
-
Select your name on the top right, then select the API Keys.
-
From the API Keys page, expand the Create section.
-
Give your API Key a name, and set the required expiry and package owner.
-
Set the scope for this API Key.
- If the package already exists, select Push and Push only new package versions. Then in the Select Packages section, select the package you want to publish updates for.
- If the package does not exist, select Push and Push new packages and package versions, then in the Glob pattern, put
*
. This will allow you to push a new package.
-
Select the Create button.
-
Once the API Key has been created, expand the Manage section, and make a copy of it using the Copy button.
-
In your C# SDK repo, add this token as an Actions secret named
NUGET_TOKEN
.
You can learn more about creating NuGet API Keys in the NuGet API Keys documentation.
To publish to the Maven Central Repository, you will need Maven credentials and a GPG key with a passphrase to sign your artifacts.
As of March 12th, 2024, the Central Portal became the default publishing server for Maven packages. At the moment, we do not support automatic publishing through the Legacy OSSRH.
Central Portal Setup
The Central Portal Account Documentation explains how to create an account. An account is required for claiming namespaces, generating credentials and managing package deployments.
Namespace Registration
Your namespace is the crucial prerequisite for publishing a package to the Central Repository as it is the groupId
of the package. The Central Repository Namespace Documentation provides detailed instructions for claiming a namespace.
The namespace verification process is not instant.
- For own domain namespaces (e.g.
com.liblab
), an additional step is required, which involves setting up the verification key as a DNS record in order for the domain name to be verified by the Central Repository. - For GitHub namespaces (namespace in the form of
io.github.githuborgname
), though, verification process is automatic if the user is registered using the GitHub SSO.
Once your namespace is verified, the next step is to generate your Maven credentials.