Skip to main content

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

This tutorial includes the following SDK languages and versions:

TypeScriptJavaPythonC#GoPHP
✅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 the languageOptions 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:

  1. Create a control repo for your API spec and liblab config file
  2. Create SDK repos for each SDK language you want to publish
  3. Create liblab and GitHub tokens
  4. Create package manager tokens
  5. Update your spec and config file
  6. Merge SDK PRs
  7. Create a release in GitHub
  8. 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.

  1. Select the button below to create a new control repo using this template.

    Control repo

  2. Give your new control repository a name, a description, and make it public or private.

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

  1. Select the relevant buttons below to create repos from the different templates:

    TypeScript SDK repo
    Python SDK repo
    C# SDK repo
    Java SDK repo
    Go SDK repo
    PHP SDK repo

  2. For each repo you create, give your new SDK repository a name, a description, and make it public or private.

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

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

  1. From the liblab CLI, run the following command to generate a liblab token:

    Terminal
    liblab 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.

    Terminal
    Token successfully generated, it will be valid for 90 days

    -TOKEN-----------------------------------------
    liblab_WoVBcuKKvwIGw2-EBjGHRjJdAJ46qggy8caFiqSP
    -----------------------------------------------
    note

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

  2. Copy the token that is generated. You need the string between the -TOKEN- and ------- lines, not those lines themselves.

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

    The liblab token set as an Actions secret

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.

  1. From GitHub, select your profile picture, then select Settings, Developer settings, Personal access tokens, then Fine-grained tokens.

  2. Give the token a name and a description

  3. Set the expiration for the token based on your needs or your organizations security policies.

    tip

    It's helpful to create a reminder for yourself such as a calendar item to refresh the token just before it expires!

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

    The repositories list with 2 sdk repos selected

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

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

    When you set these permissions, you will see the following:

    The required permissions The required permissions

  6. Add this token to your control repo GitHub Action secrets as LIBLAB_GITHUB_TOKEN.

    The liblab token set as an Actions secret

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.

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.

You should now have the following complete setup:

5. Update your spec and config file​

Now that all your repos are created and configured, you 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 has a sample API spec file using the Swagger petstore. You need to replace this with your API spec.

    • If you are using an API spec from a local file, add this to the repo, replacing the spec.json file.
    • If you are using a remote spec:
      1. Update the specFilePath option in the liblab.config.json file to point to the URL of your API spec.
      2. Delete the spec.json file from the repo.
    note

    You can leave this as the pet store spec for now, and update it later. This will allow you to test the workflow without needing to update the spec file.

  3. Update your liblab config file:

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

      1. remove any options for languages that you don't want to support.

      2. Update the githubRepoName option to match the name of the SDK repo you created for that language. 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. Update the relevant options to set 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 the changes, and push them to your control repo. This will trigger the GitHub Action to generate your SDKs, and raise PRs against 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

6. Merge SDK PRs​

Once the control repo Action is complete, you will see a PR raised against each SDK repo.

A GitHub pull request

note

If you don't see the PRs, check the Actions tab of your control repo to see if there were any errors during the SDK generation process. You can find more information on common errors in the common errors section.

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

7. 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, select Create a new release from the Releases section on the side.

    The releases section

  2. Drop down the Choose a tag button, enter a tag, and select Create new tag. The tag should be a version number using semantic versioning, and it is common to prefix the version with v, such as 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. Select Publish release to create the release.

    This will trigger the GitHub Action to publish the SDK to the relevant package manager.

8. Verify the publish​

Once the publishing Action is complete, you can check the relevant package manager to see if the SDK has been published.

🎉🎉🎉   Congratulations, you have generated and published your SDK!   🎉🎉🎉

You are now all configured to automatically generate and publish SDKs using liblab and GitHub Actions so that your latest API updates are available to your users as soon as possible.

If you do not see the packages, check the Actions tab in each SDK repo to see if there were any errors during the publish 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