Skip to main content

End-to-end SDK generation and publishing with GitHub Actions

This tutorial shows you how to use GitHub Actions with liblab to automate the SDK generation and publishing process for an existing project. You'll learn how to configure CI/CD workflows that automatically generate and release SDKs to public package managers like npm, PyPI, NuGet, Maven, Go Packages, and Packagist.

Requirements

Ensure that you:

  • Have a working liblab project with a valid OpenAPI spec and liblab.config.jsonfile.
  • Are familiar with GitHub Actions workflows. If you're new to GitHub Actions, you can find more information in the GitHub Actions documentation.
  • Have an account on the package management platform(s) you want to deploy your SDKs to (ex. NPM, PyPi, Maven). This guide will help you with all of the other deployment details.
Starting from scratch

This guide doesn't cover setting up a new liblab SDK project.

If you don't have a liblab SDK project yet then you'll first want to follow one of our framework guides or general getting started guide.

Structural Overview​

Your completed project will consist of:

  • Your existing liblab project repository which we'll refer to as the "Control Repo"
  • One SDK repository per SDK language you want to publish which are your "SDK Repos"

When you complete the tutorial, the project repository structure will look like the example below.

Where each SDK repo will have the following organization:

Any change to the API spec or liblab configuration in the Control Repo will trigger SDK builds and create pull requests (PRs) in the respective SDK repositories.

Video Version

You can find a video version of this tutorial on the liblab YouTube channel

Set up a Control Repo​

First, you'll need to set up your GitHub Workflows. Run the following command from the root of your project:

Terminal
curl --create-dirs --remote-name-all --output-dir .github/workflows "https://raw.githubusercontent.com/liblaber/control-repo-template/refs/heads/main/.github/workflows/{liblab-generate-sdks.yaml,liblab-sdk-updates.yaml}"

This command downloads the official liblab GitHub Actions files (liblab-generate-sdks.yaml and liblab-sdk-updates.yaml) and places them in the .github/workflows directory of your Control Repo.

This is what you should have so far:

Create SDK Repositories​

Your generated SDKs live in separate repos, one per SDK language.

Templates are available for each language. Click the links below and follow the instructions to create a new repository for each SDK language you want to publish.

This is what you should have so far:

Create liblab and GitHub tokens​

  1. A liblab token for authenticating the liblab CLI.
  2. A GitHub token to let the liblab CLI to push to your SDK repositories.

Create a liblab token​

Token expiration and secret management

By default, this token will expire after 90 days. You can increase this to up to 364 days by passing the --durationInDays parameter.

Read more on the liblab token command in the CLI documentation.

For guidance on setting up secrets in GitHub, refer to the GitHub secrets documentation.

To generate a liblab token, run the following command from your terminal:

liblab token create GITHUB_PR_TOKEN

You can replace GITHUB_PR_TOKEN with any name you prefer. If you're generating SDKs for multiple APIs, you can either share the token between them or create separate tokens for each API.

Token successfully generated, it will be valid for 90 days

-TOKEN-----------------------------------------
liblab_WoVBcuWKvwTGw2-EfjGHRj5dAJ4Aqzgl8caGioSP
-----------------------------------------------

Copy the token (e.g., liblab_WoVBcuWKvwTGw2-EfjGHRj5dAJ4Aqzgl8caGioSP) and save it somewhere safe. Then, add it to your Control Repo's GitHub Actions secrets as LIBLAB_TOKEN.

The liblab token set as an Actions secret

Create a GitHub token​

tip

It's helpful to create a reminder for yourself such as a calendar item to refresh your liblab and Github tokens just before they expire!

For the Action in your Control Repo to push to your SDK repositories, you'll need to generate a GitHub Fine-Grained Access Token with the right permissions. Follow these steps:

  1. Open GitHub's fine-grained token settings and click Generate new token.

  2. Enter a descriptive name and description for your token.

  3. Select the repositories this token should have access to. It's best to limit the scope of these tokens, so select only the SDK repositories you want to publish to.

    The repositories list with 2 SDK repos selected, python and typescript

  4. Set the token permissions. This token will need the following permissions:

    PermissionAccess
    Commit StatusesRead/Write
    ContentsRead/Write
    MetadataRead
    Pull RequestsRead/Write
    WorkflowsRead/Write

  5. Copy the generated token and add it to your Control Repo's GitHub Actions secrets as LIBLAB_GITHUB_TOKEN.

    The liblab token set as an Actions secret

This is what you should have so far:

Create package manager tokens​

Depending on which SDK languages you're using, you'll need to create additional secrets.

To publish to npm, you will need an npm access token. You can generate a new access token from your user settings on npm.

  1. Select the Access Tokens tab, drop down the Generate New Token button, then select Granular Access Token.

    The access tokens page in npm settings

  2. Fill in all the required details for the token such as the name and expiry.

  3. 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.

  4. Once the token has been created, make a copy of it.

  5. In your TypeScript SDK repo, add this token as an Actions secret named NPM_TOKEN.

    The token set as an actions secret

note

You can learn more about creating npm tokens in the npm access tokens documentation.

At this point, you should have a complete setup.

Update the config file​

Now that all your repositories are set up, you'll need to update the liblab.config.json file. Make sure to configure the publishing information and update the settings for each SDK language you plan to publish.

  1. In the publishing section, set the githubOrg option to the name of your GitHub organization.
  2. In the languageOptions section:

    1. Update the githubRepoName for each SDK. This should be the repo name only (e.g., typescript-sdk), not the full GitHub URL (e.g., https://github.com/myorg/typescript-sdk).

    2. Set the sdkVersion to match your desired version number. This should be updated for each new release.

    3. Configure details for each package manager:

      • Set the npmName option to the name of your npm package.
      • Set the npmOrg option to the name of your npm organization.

The following code snippet shows an example of a liblab.config.json file, where SDKs for C#, Python, TypeScript, Go, PHP, and Java are configured for generation and publishing:

Example liblab.config.json configured for SDK deployment
{
  "sdkName": "test-sdk",
  "apiVersion": "1.0.0",
  "apiName": "test-api",
  "specFilePath": "spec.json",
  "languages": [
    "csharp",
    "python",
    "typescript",
    "go",
    "php",
    "java"
  ],
  "languageOptions": {
    "csharp": {
      "liblabVersion": "2",
      "packageId": "Test.SDK",
      "githubRepoName": "csharp-sdk",
      "sdkVersion": "1.0.0"
    },
    "python": {
      "liblabVersion": "2",
      "pypiPackageName": "test-sdk",
      "githubRepoName": "python-sdk",
      "sdkVersion": "1.0.0"
    },
    "typescript": {
      "npmName": "test-sdk",
      "npmOrg": "myorg",
      "githubRepoName": "typescript-sdk",
      "sdkVersion": "1.0.0"
    },
    "java": {
      "groupId": "com.myorg",
      "artifactId": "test-sdk",
      "homepage": "https://myorg.com",
      "githubRepoName": "java-sdk",
      "sdkVersion": "1.0.0",
      "developers": [
        {
          "name": "John Doe",
          "email": "[email protected]",
          "organization": "My Organization",
          "organizationUrl": "https://myorg.com"
        }
      ]
    },
    "go": {
      "goModuleName": "github.com/myorg/go-sdk",
      "githubRepoName": "go-sdk",
      "sdkVersion": "1.0.0",
    },
    "php": {
      "packageName": "myorg/test-sdk",
      "githubRepoName": "php-sdk",
      "sdkVersion": "1.0.0"
    },
  },
  "publishing": {
    "githubOrg": "myorg"
  }
}

Finally, commit and push your changes to your Control Repo. This will trigger the GitHub Action to generate your SDKs and create PRs in your SDK repos. You can check the progress of this in the Actions tab of your Control Repo.

A complete GitHub Action to generate SDKs

Additional configuration options

There are many other options you can configure for SDK deployment but these are optional. Refer to the config file documentation to learn more.

Merge SDK PRs​

Once the Control Repo Action is done, you'll see a PR in each SDK repo.

A GitHub pull request

note

If you don't see the PRs, check the Actions tab in your Control Repo for errors. Check the common errors section for more details.

  1. Review the PRs to ensure that the changes are correct.
  2. Once you're happy, approve and merge the PRs.

Create a release in GitHub​

To trigger the Action to publish your SDK to the package manager, you need to create a release in the SDK repo. Releases need a tag to tag the commit that you want to release.

  1. From each SDK repo, go to Releases and click Create a new release.

    The releases section

  2. Click Choose a tag, enter a tag (e.g., v1.0.0), and select Create new tag.

    note

    The tag should follow semantic versioning and typically includes a v prefix, like v1.0.0.

    Note on Versioning Go Packages

    It is important to note that the release tag version will be used as the version of the package in the Go Packages repository. Therefore, it is important to follow semantic versioning and ensure that the version in the liblab.config.json file corresponds to the version of the release tag.

  3. Give the release a title and description. The title can be the same as the tag.

  4. Click Publish release. This will trigger the GitHub Action to publish your SDK.

Verify the publish​

Once the publishing Action is done, check the package manager to confirm your SDK was published.

🎉🎉🎉   Congratulations, you've generated and published your SDK!   🎉🎉🎉

You're now fully set up to automatically generate and publish SDKs with liblab and GitHub Actions, ensuring your latest API updates reach users as quickly as possible.

If you don't see the packages, check the Actions tab in each SDK repo for any errors during the publishing process.

Common errors​

If your repos are not configured correctly, you may see one of the following errors:

  • If the generate SDKs Action fails with this error:

    GitHub Actions output
    Error: Secrets LIBLAB_TOKEN and LIBLAB_GITHUB_TOKEN are required

    Then refer to the section on setting up Github and Liblab tokens. Double check that the tokens are set correctly, and that they're not expired.

  • If the generate SDKs Action fails with this error:

    Error: Unable to create branch for <language>

    You will need to check the permissions of your GitHub token, or your config file.

    • If this is for all SDK languages:
      • Verify that the GitHub organization is correctly set in the liblab config file
      • Check that your access token has the required permissions for all the SDK repositories listed in your config file
      • If you are part of a GitHub organization and not an admin, the access token you create might be pending approval. If you do not have admin permissions, you may have had to fill in a field describing why your personal access token needs access to your organization. In this case, check with your organization admins to approve the token.
    • If the error is only for one SDK language, check that the GitHub repo name is correct in the liblab config file options for that language.
Last updated on