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. It'll 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.

tip

Before getting started you'll want to make sure you have a liblab account and the liblab CLI installed.

Ensure that you:

  • Have an existing liblab project with an API specification file.
  • 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 you intend to use.

Supported SDK languages:

TypeScript /
Javascript		Java /
Kotlin		PythonC#GoPHP
✅✅✅✅✅✅

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 the languageOptions section for the relevant language is set as required.

Structural Overview​

Your completed project will consist of:

  • A control repo containing your existing liblab project.
  • One SDK repository per SDK language you want to publish.

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

Any change to the API specification or liblab configuration in the control repository 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

Create 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 is what you should have so far:

Starting from a new repository

If you prefer to start with a new repository, liblab provides a template repository to help you get started. Click here to create a new control repository on GitHub. For more details, check out the control repo documentation.

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.

If you need more information on setting up secrets in GitHub, check ou the GitHub secrets documentation.

Run the following command in the liblab CLI to generate a liblab token:

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.

Terminal
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. Add this new token to your Control Repository's 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 repository’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 your spec and config file​

Now that all your repos are set up, you'll need to update the contents of the control repo with your API spec, and configure the liblab config file.

  1. Check out your control repo and open it in your code editor. You can also open the repo in a GitHub codespace or edit individual files through the GitHub web UI.

  2. The control repo includes a sample API spec file using the Swagger Petstore. You need to replace this with your own API spec.

    • If you're using a local API spec file, add it to the repo, replacing the spec.json file.

    • If you're using a remote spec:

      1. Update the specFilePath option in liblab.config.json to point to your API spec's URL.

      2. Delete the spec.json file from the repo.

    note

    You can leave this as the Petstore spec for now and update it later. This way, you can test the workflow without needing to change the spec file.

  3. Update your liblab config file:

    1. Update the sdkName, apiName, and apiVersion options to match your API and the SDK name.
    2. Update the languages for the SDK languages you want to generate.
    3. In the languageOptions section:

      1. Remove options for languages you don't want to support.

      2. Update the githubRepoName for each SDK. This just needs to be the repo name, not the full URL (for example, typescript-sdk not https://github.com/myorg/typescript-sdk).

      3. Update the sdkVersion option to the version number you want to use for each SDK.

      4. 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.
    4. In the publishing section, set the githubOrg option to the name of your GitHub organization.
    5. There are other options you can configure, but these are not required for now. To learn more, see the config file documentation.

    When complete, your config file should look something like this:

    liblab.config.json
    {
      "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"
      }
    }

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

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 you haven't set up the LIBLAB_TOKEN or LIBLAB_GITHUB_TOKEN secrets correctly. Check that the tokens are set correctly, and that the tokens are valid.

  • 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