Integrate with GitHub Actions

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.

Prerequisites

This tutorial assumes you already have an API spec, and have been successful in generating SDKs using liblab. If you haven't done this yet, check out our Generate an SDK from your OpenAPI spec guide to generate your first SDK from an OpenAPI spec you already have.

You will also need a GitHub account, and the ability to create new repositories in your GitHub organization, or in your personal account.

Steps

In this tutorial you will:

1. Prepare your SDK for publishing
2. Create tokens
3. Create the GitHub action
4. Test the workflow

Prepare your SDK for publishing

To automate our builds, we will create a new Github repo to be our API source of truth. We will use Github actions to trigger a new build to generate SDKs and documentation. This trigger can be manual, or on every API update, such as via a pull request.

If your spec is remote via a publicly reachable URL, for example auto-generated by an API gateway, then you will need to manually trigger this action. If the spec is a local file, then you can trigger this action when that file changes.

Create a control repo

We will start by creating a new Github repo that will host our API spec file and liblab.config.json file. You can create the config file by running liblab init.

This is what a typical Control Repo looks like:

.
├── spec.json
└── liblab.config.json

The spec file is optional if your spec is set in the config file to a URL.

note

If your API spec lives in an existing repo, you can set that up as a control repo - you will need to add the liblab config file to that repo, pointing to the folder that the spec lives in.

Create SDK repos

Besides the Control Repo we also need to have repos for each SDK language. These are the repositories where published SDKs source code lives.

For instance if your github organization name is exciting-soda you could have the following repos:

• exciting-soda/java-sdk
• exciting-soda/python-sdk
• exciting-soda/typescript-sdk

The repository names can be set to whatever you choose, just make sure you have one repo per SDK language.

Update your config file

The liblab.config.json file in your Control Repo needs to include the information about your SDK repos.

• publishing.githubOrg: This is the name of your GitHub organization. This is where your SDKs will be published. Set this to the name of your GitHub organization without any other symbols or characters.
• languageOptions.[language].githubRepoName: Configure the githubRepoName for any language you plan on publishing. This should be the name of the repo without the organization name or any other parts of the URL.

For example, with a GitHub organization of exciting-soda and the following repos:

• exciting-soda/java-sdk
• exciting-soda/python-sdk
• exciting-soda/typescript-sdk

Then your config file should look like this:

{
    "languageOptions": {
        "typescript": {
            "githubRepoName": "typescript-sdk",
            ...
        },
        "python": {
            "githubRepoName": "python-sdk",
            ...
        },
        "java": {
            "githubRepoName": "java-sdk",
            ...
        }
    },
    "publishing": {
        "githubOrg": "exciting-soda"
    },
    ...
}

Create tokens

To publish SDK code using GitHub actions you will need 2 tokens - a liblab token to allow the liblab CLI to run logged in as you during the action, and a GitHub token to allow the liblab CLI to push to your GitHub repos.

Create a liblab long-lived token

The liblab CLI requires you to be logged in to use it. In a GitHub action you are unable to log in as these are run non-interactively. In this case you can log in by using a long-lived token set as an environment variable.

To create a long lived token called GITHUB, run the following command:

liblab token create GITHUB

You will need to authenticate again.

Token successfully generated, it will be valid for 90 days

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

note

These long-lived tokens have a default expiry date 90 days after generation. You can increase this to 364 days by passing the time in the --durationInDays parameter.

You will need to track this expiry and re-generate a new token before the expiry date.

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 long-lived 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.

This token will need the following permissions for all your SDK repos:

Permission	Access
Commit Statuses	Read/Write
Contents	Read/Write
Metadata	Read
Pull Requests	Read/Write
Workflows	Read/Write

You will need to add this token to your GitHub secrets as LIBLAB_GITHUB_TOKEN.

Create the GitHub action

Now you have your repos set up and your tokens created, you can create the GitHub action that will run the liblab CLI to generate and publish your SDKs.

Create a new Github workflow

Add a Github workflow that will generate SDKs and publish them to the relevant GitHub repos. In your Control Repo, create a .github/workflows/liblab-generate-sdks.yaml file with this content:

name: Generate SDKs using liblab

on:
  # Add any other triggers you want here, such as a push to the spec file
  workflow_call:
  workflow_dispatch:

jobs:
  build-and-pr:
    name: Generate SDKs and create PRs
    runs-on: ubuntu-latest
    env:
      LIBLAB_TOKEN: ${{ secrets.LIBLAB_TOKEN }}
      GITHUB_TOKEN: ${{ secrets.LIBLAB_GITHUB_TOKEN }}
    environment: development
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Node.js environment
        uses: actions/setup-node@v3
        with:
          node-version: "18" # Specify the node version you want to use
      - name: Install liblab
        run: npm install -g liblab
      - name: Start Build
        run: liblab build --skip-validation --approve-docs
      - name: Create PRs to GitHub repos
        run: liblab pr

Your updated Control repo should have these files:

.
├── spec.json
├── liblab.config.json
└── .github
    └── workflows
        └── liblab-generate-sdks.yaml

This workflow will generate SDKs based on your configuration file, run some post build steps and then create PRs to your SDK repos. You can trigger this workflow manually or automatically.

This workflow uses the liblab pr command. This command will generate the new SDKs, push the code for the generated SDKs into new branches in the relevant repos, and raise pull requests to merge these to the main branch.

Test the workflow

You can test the workflow by triggering it manually. To do this, go to the Actions tab in your Control Repo and select the Generate SDK using liblab workflow. Then select the Run workflow button.

Once the workflow runs you will be able to see the output, and fix any issues that occur, such as if the tokens are not set correctly.

You will also be able to see the PRs that are created in your SDK repos. From here you can review the code changes and merge the PR.

note

It is good practice to review the created SDKs in case of breaking changes in your API spec that would lead to breaking changes in the SDKs. If this happens, it is good practice to follow semantic versioning and bump the major version of the SDK.

Common errors

If your action is not configured correctly, you may see one of the following errors:

• If the Start Build step does not complete, and you see multiple entries of Waiting for confirmation and login at browser... ⡿ in the logs, then you haven't set up the LIBLAB_TOKEN secret correctly. Check that the token is set correctly, and that the token is valid.
• If you see the error Error: Unable to create branch for <language> in the Create PRs to GitHub repos step, then your GitHub fine grained access token is not set up correctly. You can find more details on this in the liblab pr documentation.