Skip to main content

Control and SDK repos

A control repo is a repository that contains the source of truth for everything you need to generate an SDK with liblab, and controls your SDK generation when using liblab in a CI/CD pipeline. SDK repos are where you generated SDKs live.

Control repo​

A control repo contains at the minimum your liblab config file. It can also contain your API spec if you are using a local file, and code for hooks or custom plan modifiers. It can also contain Actions to trigger SDK generation in a CI/CD pipeline.

.
├── .github
│   └── workflows
├── spec.json
├── liblab.config.json
├── customPlanModifiers
│   ├── attributes
│   └── resources
└── hooks
    ├── go
    ├── csharp
    ├── java
    ├── python
    ├── terraform
    └── typescript

Create a control repo​

liblab provides a template repo that you can use to get started. This contains a basic config file that you can configure, an example spec, and GitHub Actions to update your SDKs when your spec changes, or when liblab releases an update.

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

Create your control repo

Regenerate SDKs using GitHub Actions​

One of the powerful features of liblab is the ability to regenerate your SDKs when your spec changes. This can be done using GitHub Actions to give a hands off experience - once your spec changes, liblab will re-generate your SDK and raise pull requests for you to review in your SDK repos.

In your control repo, you will need 2 Actions - one to check for updates to your spec, config file, or hooks code, and one to check for liblab updates. If you create your control repo using the template repo mentioned above then these Actions will already be set up for you.

Configure secrets​

These Actions need 2 Actions secrets set - LIBLAB_TOKEN and LIBLAB_GITHUB_TOKEN.

Check for updates to your spec​

The control template repo contains a GitHub Action that monitors the spec file in the repo, hooks code, as well as the liblab config file, for changes. If any of these files change, the SDK is regenerated and a pull request is raised in the SDK repos.

The GitHub Action has the following code:

name: Generate SDKs using liblab

on:
  workflow_call:
  workflow_dispatch:
  push:
    branches:
      - main
    paths:
      - 'liblab.config.json'
      - 'spec.json'
      - 'hooks/**'
      - 'customPlanModifiers/**'
jobs:
  build-and-pr:
    name: Generate SDKs and create PRs
    runs-on: ubuntu-latest
    if: github.run_number != 1
    env:
      LIBLAB_CI: true
      LIBLAB_TOKEN: ${{ secrets.LIBLAB_TOKEN }}
      LIBLAB_GITHUB_TOKEN: ${{ secrets.LIBLAB_GITHUB_TOKEN }}
    steps:
      - name: Check if secrets are set
        run: |
          if [[ -n "${{ secrets.LIBLAB_TOKEN }}" && -n "${{ secrets.LIBLAB_GITHUB_TOKEN }}" ]]; then
            echo "Secrets are set, proceeding with the workflow"
          else
            echo "Error: Secrets LIBLAB_TOKEN and LIBLAB_GITHUB_TOKEN are required, see /docs/tutorials/ci-cd/integrate-with-github-actions/#create-tokens"
            echo "::error::Secrets LIBLAB_TOKEN and LIBLAB_GITHUB_TOKEN are required, see /docs/tutorials/ci-cd/integrate-with-github-actions/#create-tokens"
            exit 1
          fi
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node.js environment
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install liblab
        run: npm install -g liblab
      - name: Start Build
        run: liblab build --yes
      - name: Create PRs to GitHub repos
        run: liblab pr

This Action watches for changes to the config file, spec and hooks code on the main branch. If you use a different file structure, a different branch name, or a different name for your spec file, you can update the push event.

Once a change is detected, it will verify that you have the secrets configured correctly, then build the SDK, and create a pull request in your SDK repos.

Check for liblab updates​

When liblab releases an update, you can use a GitHub Action to detect this and regenerate your SDKs. These updates may include bug fixes and other improvements to the generated SDKs, but will not create any breaking changes in the generated SDK.

This Action is included in the control template repo, and uses an SDK Updates Action published by liblab on the GitHub marketplace.

The GitHub Action has the following code:

name: Latest liblab updates

on:
  workflow_dispatch:
  schedule:
    - cron: '0 11 * * *' # 11am UTC corresponds to 5am CST

jobs:
  generate-sdks-and-publish-prs:
    name: Generate SDKs and publish PRs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate SDKs and publish PRs
        uses: liblaber/sdk-[email protected]
        with:
          liblab_token: ${{ secrets.LIBLAB_TOKEN }}
          liblab_github_token: ${{ secrets.LIBLAB_GITHUB_TOKEN }}

This code runs at 11am UTC every day, and checks for updates to liblab. If an update is detected, it will regenerate your SDKs and raise a pull request in your SDK repos. You can change the schedule to suit your needs by updating the cron schedule.

SDK repos​

SDK repos are where your generated SDKs live, one per SDK language. From here you can publish your SDKs to a package manager if required.

Your liblab config file should be configured to point to these SDK repos to allow pull requests to be raised by your control repo. This is done using the githubRepoName config file option for each SDK language.

You can use GitHub Actions to publish your SDKs to a package manager when you release a new version.

Create an SDK repo​

liblab provides template repos to generate SDK repos that have GitHub Actions that publish to the relevant package manager when you create a release.

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

If you create an SDK repo manually, make sure to create the default branch. If you see this error when creating a PR using the liblab CLI or GitHub Action:

Default branch: main does not exists in the repository

Then check that you have created the main branch in your repo.

Configure the SDK repos​

To publish to a package manager, you will need to configure the GitHub Actions in your SDK repos, including setting Actions 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.

Last updated on