Skip to main content

End-to-end SDK generation and publishing with GitLab Pipelines

Supported SDK languages:

TypeScript /
Javascript		Java /
Kotlin		PythonC#GoPHP
✅✅✅✅✅✅

This tutorial shows you how to use GitLab pipelines with liblab to automate the SDK generation and publishing process for an existing project. You'll learn how to configure CI/CD workflows that automatically generate and release SDKs to public package managers like npm, PyPI, NuGet, Maven, Go Packages, and Packagist.

Requirements

Ensure that you:

  • Have a working liblab project with a valid OpenAPI spec and liblab.config.jsonfile.
  • Have an account on the package management platform(s) you want to deploy your SDKs to (ex. NPM, PyPi, Maven). This guide will help you with all of the other deployment details.

If you're new to GitLab pipelines, you can find more information in the CI/CD pipelines documentation.

Starting from scratch

This guide doesn't cover setting up a new liblab SDK project.

If you don't have a liblab SDK project yet then you'll first want to follow one of our framework guides or general getting started guide.

Structural Overview​

Your completed project will consist of:

  • Your existing liblab project repository which we'll refer to as the "Control Repo"
  • One SDK repository per SDK language you want to publish which are your "SDK Repos"

When you complete the tutorial, the project repository structure will look like the example below.

Where each SDK repo will have the following organization:

Any change to the API spec or liblab configuration in the Control Repo will trigger SDK builds and create pull requests (PRs) in the respective SDK repositories.

Set up the Control Repo​

First, you'll need to set up your GitLab pipeline. Run the following command from the root of your project:

Terminal
cd your-liblab-project
curl --create-dirs --output .gitlab-ci.yml https://raw.githubusercontent.com/liblaber/control-repo-template/refs/heads/main/.gitlab-ci.yml

This command downloads the official liblab Bitbucket pipeline file (.gitlab-ci.yml) and places them in the root of your Control Repo.

.gitlab-ci.yml

This file automates the SDK generation process and creates pull requests for changes in specific files, such as liblab.config.json and directories like hooks and customPlanModifiers. It triggers on pushes to the main branch or manual web actions to execute the build. You can customize it as needed.

This is what you should have so far:

Create SDK Repos​

Each generated SDK lives in its own repository, one per SDK language. Therefore, you need to create a new repository for each SDK language you plan to publish. In each repository, you must include a CI/CD configuration file (.gitlab-ci.yml) to ensure the SDK is automatically published to the correct package manager always it's updated.

You don’t need to write the pipeline configuration yourself, we’ve already done that for you. Use the links below to access the most up-to-date .gitlab-ci.yml files from the official liblab SDK template repositories:

This is what you should have so far:

Create liblab and GitLab tokens​

The GitLab CI/CD pipeline in the Control Repo requires two secrets to generate SDKs:

  1. A liblab token for authenticating the liblab CLI.
  2. A GitLab access token to let the liblab CLI to push to your SDK repos.

Create a liblab token​

Token expiration and secret management

By default, this token will expire after 90 days. You can increase this to up to 364 days by passing the --durationInDays parameter.

Read more on the liblab token command in the CLI documentation.

For guidance on setting up variables in GitLab, refer to the GitLab CI/CD variables documentation.

To generate a liblab token, run the following command from your terminal:

liblab token create LIBLAB_TOKEN

You can replace LIBLAB_TOKEN with any name you prefer. If you're generating SDKs for multiple APIs, you can either share the token between them or create separate tokens for each API.

Token successfully generated, it will be valid for 90 days

-TOKEN-----------------------------------------
liblab_HYeJzYb5CO3t7JaW4I6ZWKNKbOGp01MqqYSTS6yG
-----------------------------------------------

Copy the token (e.g., liblab_HYeJzYb5CO3t7JaW4I6ZWKNKbOGp01MqqYSTS6yG) and save it somewhere safe. The token will allow liblab to authenticate during the CI/CD pipeline run. Then, add the token to your Gitlab Control Repo project:

  1. Access your GitLab project.
  2. Navigate to Settings > CI/CD > Variables and click Add variable.
  3. For Key, use LIBLAB_TOKEN and paste the liblab token into the Value field and click Add variable.

Add liblab token as variable to GitLab

Create a GitLab access token​

To enable the GitLab pipeline to run the liblab CLI and push changes to your SDKs repos, you need to generate a GitLab personal access token:

  1. In GitLab, click at your profile picture and select Preferences.

  2. Access the Access tokens tab from the sidebar.

  3. Select Add new token.

  4. Enter a name (e.g., liblab-token) and an expiration date based on your organization's security policy.

    tip

    It's helpful to create a reminder for yourself such as a calendar item to refresh your liblab and GitLab tokens just before they expire!

  5. Select the following scopes:

    • api
    • read_repository
    • write_repository
    • read_user

  6. Select Create personal access token and copy the generated token. This token will be used to authenticate and push SDKs to your SDK repos.

  7. Add this token to your GitLab project's Settings > CI/CD > Variables as LIBLAB_GITLAB_TOKEN.

Control Repo variables

This is what you should have set up so far:

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:

Update the config file​

Now that all your repositories are set up, you'll need to update the liblab.config.json file. Make sure to configure the publishing information and update the settings for each SDK language you plan to publish.

  1. In the publishing section, set the githubOrg option to the name of your GitHub organization.
  2. In the languageOptions section:

    1. Remove any unused languages. If there are languages you don't need, remove their configuration.

    2. Update the githubRepoName for each SDK. liblab will use it to identify the GitLab project that matches the name of the corresponding SDK repo.

    3. Set the sdkVersion to match your desired version number. This should be updated for each new release.

    4. Configure 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.
Additional configuration options

There are many other options you can configure for SDK deployment but these are optional. Refer to the config file documentation to learn more.

The following code snippet shows an example of a liblab.config.json file, where SDKs for C#, Python, TypeScript, Go, PHP, and Java are configured for generation and publishing:

Example liblab.config.json configured for SDK deployment
{
  "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"
  }
}

Finally, commit and push your changes to your Control Repo. This will trigger the GitLab pipeline to generate your SDKs and create PRs in your SDK repos. Go to Build > Pipelines or Build > Jobs to check the pipeline and job status in the Control Repo.

Log In to Complete the Job

When the pipeline starts a new job to build an SDK, the liblab CLI may require you to log in and confirm an authorization code. A link to the login page will be provided in the job logs within GitLab.

Running job

If you don't log in and confirm the code, the job may not be complete, and the SDK build will not be triggered.

Merge SDK PRs​

Once the Control Repo job is completed successfully, you'll see a PR in each SDK repo.

New PR created by liblab CLI

Check the PRs generated by liblab in each SDK repo, accessing Code > Merge requests.

note

If you don't see the PRs, check your Control Repo's CI/CD > Pipelines or Jobs section for any errors during the SDK generation process. You can also refer to the common errors section for troubleshooting.

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

Create a release in GitLab​

You need to create a release in the SDK repo to trigger the Action to publish your SDK to the package manager. To create a release, follow the steps below:

  1. From each SDK repo, access Deploy > Releases and click Create a new release.

  2. On the release page:

    1. Provide a Tag name. 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 repo. 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.

    1. Give the release a Release title. The title can be the same as the tag.
    2. Add a Milestone. You can create one if necessary.
    3. Define the Release date and add the Release notes.

  3. Click Create release. This will trigger the pipeline to publish your SDK.

Release notes

Confirm SDK publication​

Once the publishing Action is done, check the package manager to confirm your SDK was published.

🎉🎉🎉   Congratulations, you've generated and published your SDK!   🎉🎉🎉

Your setup is now fully automated to generate and publish SDKs with liblab and GitLab CI/CD, ensuring your latest API updates are quickly available to your users.

If you don’t see the SDK in the package manager, check the CI/CD > Pipelines or Jobs section in each SDK repo to troubleshoot any errors during the publishing 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:

    Error: Secrets LIBLAB_TOKEN and LIBLAB_GITLAB_TOKEN are required

    Then you haven't set up the LIBLAB_TOKEN or LIBLAB_GITLAB_TOKEN secrets correctly. Check that the tokens are set correctly, and that the tokens are valid.

Last updated on