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.
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
.
LIBLAB_TOKEN
is a liblab access token created usingliblab token create
LIBLAB_GITHUB_TOKEN
is your GitHub token. You can find more information on how to create a GitHub token with the correct permissions in our pull request documentation
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 https://developers.liblab.com/tutorials/integrate-with-github-actions/#create-tokens"
echo "::error::Secrets LIBLAB_TOKEN and LIBLAB_GITHUB_TOKEN are required, see https://developers.liblab.com/tutorials/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-updates@v1.0.0
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.
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.