Skip to main content

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

Supported SDK languages:

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

This tutorial shows you how to use Bitbucket 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 a Bitbucket account.
  • 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 Bitbucket Pipelines, you can find more information in Bitbucket's 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 Bitbucket pipeline. Run the following command from the root of your project. This command downloads the official liblab Bitbucket pipeline file (bitbucket-pipelines.yml) and places it in the root of your Control Repo.

Terminal
cd your-liblab-project
curl -o bitbucket-pipelines.yml https://raw.githubusercontent.com/liblaber/control-repo-template/main/bitbucket-pipelines.yml
bitbucket-pipelines.yml

This file automates SDK generation and pull request (PR) creation when changes occur in specified files and directories, such as liblab.config.json, spec/, hooks, and customPlanModifiers. It triggers on pushes to the main branch and on pull requests. You can customize it to your own project's needs.

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 (bitbucket-pipelines.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 bitbucket-pipelines.yml files from the official liblab SDK template repositories:

This is what you should have so far:

Create liblab and Bitbucket tokens​

The Bitbucket pipeline in the Control Repo, which generates SDKs, requires two tokens that you'll create in the next steps.

  • A LIBLAB_TOKEN for authenticating the liblab CLI.
  • A LIBLAB_BITBUCKET_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 Bitbucket, refer to the variables and secrets documentation.

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

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.

Terminal
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.

Then, add the token to your Bitbucket Control Repo project.

  1. Access your Bitbucket project.
  2. Navigate to Settings > CI/CD > Variables and click Add variable.
  3. Set Key to LIBLAB_TOKEN and paste the token in the Value field, then click Add variable.

Add liblab token as variable

Create a Bitbucket access token​

To enable the Bitbucket pipeline to run the liblab CLI and push changes to your SDK repos, you need a Bitbucket access token. Follow these steps to create a project access token:

Access Token Scope

liblab recommends using a Project access token. If the Control Repo and SDK repos are in the same project, this limits the token's access scope to necessary repos.

For non-premium accounts, consider creating a repository access token for the SDK repo. However, this restricts usage to one SDK repo.

  1. In Bitbucket, go to Projects and select the project containing the Control Repo and SDK repos.
  2. In the left sidebar, choose Project settings.
  3. Select Access tokens.
  4. Set Label to LIBLAB_BITBUCKET_TOKEN.
  5. Assign the following permissions:
    • Repositories:
      • Read
      • Write
    • Pull Request:
      • Read
      • Write
  6. Click Create and copy the generated token. This token will authenticate and push SDK code to your SDK repos from the Control Repo.
  7. Add the token as a repository variable in your Control Repo, with the name LIBLAB_BITBUCKET_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 a repository variable 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.

At this point, you should have a 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 Bitbucket workspace that contains the SDK repos.

  2. In the languageOptions section:

    1. Update the githubRepoName for each SDK. This should be the name of the corresponding Bitbucket SDK repo (e.g., typescript-sdk).

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

    3. 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
liblab.config.json
{
  "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": "bitbucket.org/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 pipeline to generate your SDKs and create PRs in your SDK repos. To check the progress, access the pipeline view to check the pipeline and job status.

Merge SDK PRs​

Once the Control Repo pipeline completes successfully, a PR will be created in each SDK repo. To view these PRs, select Pull requests in each SDK repo.

New PR created by liblab CLI

note

If you don't see the PRs, check the Pipelines tab in your Control Repo for any errors. Refer to the common errors section section for troubleshooting tips.

To complete the process:

  1. Review the PRs to ensure the SDKs were generated correctly.
  2. Once you're happy, approve and merge the PRs.

Create a release in Bitbucket​

Bitbucket does not provide a native way of automatically generating release notes. You can use a third-party solution or create release notes using Jira. Access the Atlassian tutorial page for more information.

Confirm SDK publication​

After completing the publishing process, check the package manager services related to the SDKs you have created, such as npm, PyPI, and Maven, to verify that your SDK has been successfully published.

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

You're now fully set up to automatically generate and publish SDKs with liblab and Bitbucket pipelines, ensuring your latest API updates reach users as quickly as possible.

If you don't see the SDK in the package manager, check the Pipelines 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:

    Bitbucket pipeline output
      Error: Secrets LIBLAB_TOKEN and LIBLAB_BITBUCKET_TOKEN are required

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

  • If the pipeline generates the SDKs but fails to create a pull request in the SDK repo, presenting an error similar to the next one:

    Bitbucket pipeline output
        Error occurred while creating PR for Python: Access to push changes to  branch v1.0.0-1730738768515 is forbidden

    Then, your LIBLAB_BITBUCKET_TOKEN access token does not have the necessary permissions. Remember, you have to create a workspace or project access token. Only use the Repository access token if you are using the free account. Don't use the Bitbucket app password in the access token place.

Last updated on