Skip to main content

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:

  • The liblab CLI installed and you are logged in
  • An API spec
  • A generated SDK. 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.
  • A GitHub account, with the permissions 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.

The liblab token set as an actions secret

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:

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

The required permissions The required permissions

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

The liblab token set as an actions secret

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 --yes
- 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. The liblab build command has the --yes flag set to answer Y to all questions - this will ignore any validation errors, download the SDK overwriting any existing SDKs, and approve the SDK documentation if you have createDocs set to true in your config file.

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.

The run workflow button for the generate SDKs using liblab github action

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.

The results of a successful github actions run

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.

A PR raised by the action

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.