Skip to main content

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

This tutorial includes the following SDK languages and versions:

TypeScript v1TypeScript v2Java v1Java v2Python v1Python v2C#GoPHP
✅✅✅✅✅✅✅✅✅

This tutorial will guide you through the process of setting up an end-to-end automated workflow to generate, manage, and publish SDKs using liblab and Bitbucket Pipelines. You'll learn how to configure a control repo to store your API specifications, define SDK repos for different programming languages, and set up tokens to automate the deployment of your SDKs to package managers such as npm, PyPI, and Maven.

By the end of this tutorial, you'll have an automated pipeline that ensures your latest API updates are made available quickly to your users through automatically generated and published SDKs.

Prerequisites​

To follow this tutorial, you'll need the following:

Steps​

This tutorial covers the following steps:

  1. Create a control repo
  2. Create SDK repos
  3. Create liblab and Bitbucket tokens
  4. Create package manager tokens
  5. Update your spec and config file
  6. Merge SDK PRs
  7. Create a release in Bitbucket
  8. Confirm SDK publication

1. Create a Control Repo​

To begin, set up a control repo as the main storage for your liblab config file, any hooks code, and the API spec.

OpenAPI Spec

Storing the OpenAPI spec directly in the control repo isn't required. You can link to an external repo through the liblab.config.json file.

To streamline setup, use the control-repo-template. For more details, access the control repo documentation. The control-repo-template provided by liblab includes:

FileDescription
bitbucket-pipelines.ymlAutomates 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. This pipeline uses a Node.js environment to detect changes, install liblab, and create a PR in Bitbucket if updates are found. Configure LIBLAB_TOKEN and LIBLAB_BITBUCKET_TOKEN to ensure correct execution.
liblab.config.jsonSample liblab config file containing the settings used by the liblab CLI to generate SDKs.
spec.jsonExample OpenAPI spec based on Petstore. The liblab.config.json file is refering this OpenAPI spec.
.github/workflowsDirectory with two GitHub Actions. One creates PRs for your SDKs when your API spec or config file changes, and another polls for liblab updates, creating PRs for SDK updates. These GitHub Actions are adapted for use with Bitbucket.

Since the control-repo-template is hosted on GitHub, follow these steps to integrate it with Bitbucket:

  1. Log in to your Bitbucket account.

  2. Create or join a Bitbucket workspace.

  3. In the navigation bar, select Create > Repository:

    • Choose an existing project or create a new one.
    • Enter a Repository name.
    • Uncheck Private repository.
    • Select No for Include a README and Include .gitignore.
    • Set main as the Default branch name.
    • Click Create repository.

  4. Clone the GitHub-hosted control-repo-template to your local machine:

Terminal
git clone https://github.com/liblaber/control-repo-template
  1. Navigate to the cloned repo on your machine, then add your new Bitbucket repo as a remote:
cd control-repo-template
git remote rename origin old-origin
git remote add origin https://<your-bitbucket-organization>/<your-bitbucket-project>/control-repo.git
  1. Push the control-repo-template to your Bitbucket repo:
git push -u origin main

If it's your first time using Bitbucket, a new windows will show up asking you to connect with Bitbucket.

Connect to Bitbucket

This is what you should have on your Bitbucket project:

2. Create SDK repos​

Each SDK you create requires a dedicated repo for storage and publication. These SDK repos should be created before you can publish your SDKs. You can set up these SDK repos manually or use one of the liblab templates.

To get started, create a new Bitbucket project for each SDK language, or use liblab's available templates:

If you're using a liblab template, follow the steps in Step 1 to push the template content to your Bitbucket repos.

Each liblab template includes a Bitbucket pipeline file, automating the SDK's build and deployment process to the package manager service.

note

For more information on SDK repos, access the SDK repos documentation.

After setting up the SDK repos, you should have the following:

3. Create liblab and Bitbucket tokens​

The Bitbucket pipeline in the control repo, which generates SDKs, requires two tokens:

  • LIBLAB_TOKEN: A liblab token that authenticates the liblab CLI.
  • LIBLAB_BITBUCKET_TOKEN: A Bitbucket access token that allows the liblab CLI to push content to your SDK repos.

3.1 Create a liblab token​

To create the liblab token, follow these steps:

  1. On your machine, use the liblab CLI to generate a liblab token:

    Terminal
    liblab token create LIBLAB_TOKEN

    You can replace LIBLAB_TOKEN with any preferred name. If you're generating SDKs for multiple APIs, you can either use the same token for all APIs or generate separate tokens for each.

    Terminal
    Token successfully generated, it will be valid for 90 days

    -TOKEN-----------------------------------------
    liblab_HYsJnYb5Ch6EhlSdlNuF_qurwUEGQg75fw9H8bEE
    -----------------------------------------------
    note

    By default, the token expires after 90 days. You can extend this to up to 364 days by using the --durationInDays parameter.

    See the CLI documentation for more information about the liblab token command.

  2. Copy the generated token string (liblab_...) from the central line. This token will allow liblab to authenticate during CI/CD when the pipeline runs.

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

Add liblab token as variable

3.2 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:

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

You should now have the following complete setup:

5. Update your spec and config file​

After setting up your SDK repos, the next step is to update your control repo with your API spec and configure the liblab.config.json file.

Follow these steps to update your API spec and trigger the release of new SDKs to their respective repos:

  1. Open the control repo you cloned in Step 1 on your machine.

  2. Replace the control repo's sample OpenAPI spec (spec.json) with your API spec. To follow this tutorial, you can keep the existing sample file.

    • If you have a local OpenAPI spec, replace the spec.json file directly.
    • For a remotely hosted API spec:
      1. Update the specFilePath field in the liblab.config.json file with the URL of your remote API spec.
      2. Delete the spec.json file from the repo if you're using a remote spec.

  3. Open the liblab.config.json file in your control repo and update the following fields:

    • sdkName: Enter the name of your SDK.
    • apiName: Enter the name of your API.
    • apiVersion: Specify the API version.
    • languages: List the SDK languages to generate, such as TypeScript, Python, and Go.

  4. In liblab.config.json, locate the languageOptions section to configure each SDK language:

    1. Remove configurations for any unused languages.

    2. For each language, update the githubRepoName field with the name of the corresponding Bitbucket SDK repo. liblab will use it to create the pull request with the new SDK code.

    3. Set the sdkVersion for each SDK.

    4. Configure the package manager options as follows:

      • Set the npmName option to the name of your npm package.
      • Set the npmOrg option to the name of your npm organization.

    5. In the publishing section, set githubOrg to the Bitbucket workspace that contains the SDK repos.

    tip

    Additional optional settings are available in the liblab config file documentation.

    Your liblab.config.json file should look like this:

    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"
      }
    }

  5. Commit the changes you performed to the liblab.config.json and OpenAPI spec files.

  6. Push the updates to your control repo to trigger the pipeline, generating your SDKs and creating pull requests in the SDK repos.

6. Merge SDK PRs​

In the control repo, navigate to Pipelines to check the pipeline and job status. Once the pipeline in the control repo completes, a pull request PR will be automatically generated in each SDK repo.

After the job completes successfully in the control repo, review the PRs generated by liblab 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 control repo's Pipelines for any errors during the SDK generation process. You can also refer to the common errors section for troubleshooting.

To complete the process:

  1. Open each PR in the SDK repos and review the changes to ensure the SDK was generated correctly.
  2. If all changes are correct, approve the PRs and merge them into the main branch.

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

8. 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 have successfully generated and published your SDK!   🎉🎉🎉

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

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