Skip to main content

PR creation

Once you have built your SDK, liblab can create pull requests to help automate the process of updating your SDK code in your source code repository. This process is designed to be run in your CI/CD pipeline.

At the moment the only source code repository that is supported is GitHub.

Access to your GitHub repo

Pull requests are made against the repositories defined in the language specific sections of your liblab config file, with each language using a different repository. The GitHub user or organization that owns the repositories is also defined in the config file.

For the liblab CLI to be able to create a PR, it needs a fine-grained GitHub access token set in an environment variable called GITHUB_TOKEN, This token needs the following repository permissions for the repos you want to create the PR in.

PermissionAccess
Commit StatusesRead/Write
ContentsRead/Write
MetadataRead
Pull RequestsRead/Write
WorkflowsRead/Write

When you set these permissions, you will see the following:

The required permissions The required permissions

note

You will need to use a fine-grained token, not a classic token.

This token can be set from your terminal for local testing, and configured as an environment variable in your CI/CD pipeline.

note

If you get the following error when running liblab pr command:

Error: Unable to create branch for <language>

You will need to check the permissions of your GitHub token, or your config file.

  • If this is for all SDK languages, then check your access token:
    • Check that the token has the required permissions for all the SDK repositories listed in your config file
    • If you are part of a GitHub organization and not an admin, the token you create might be pending approval. If you do not have admin permissions, you may have had to fill in a field describing why your personal access token needs access to your organization. In this case, check with your organization admins to approve the token.
  • If the error is only for one SDK language, check that the repo name is correct in the configuration file options for that language.

The PR creation process

You can create a PR using the liblab pr command, combined with the GITHUB_TOKEN environment variable.

The PR creation process is as follows:

  1. A new branch is created in the repo with a unique name, based off the main branch. This new branch is checked out locally to a temporary folder.
  2. As part of the SDK generation, liblab generates a manifest file called .manifest.json that lists all the files that were generated. The liblab CLI will use this file to determine what files have changed, and makes the relevant changes to the local repo.
    • The existing manifest in the repo and the new manifest are compared. Any files that are in the existing manifest but not in the new manifest are deleted from the local branch.
    • All files from the newly generated SDK are copied into the local branch.
    • Any additional files that have been added to the repo will not be touched by this process.
  3. Once the files have been updated, the CLI will commit the changes to the local branch, and push this to the remote repo.
  4. Finally, the CLI will create a PR in the remote repo to merge the branch to your main branch.

Approving and merging the PRs

liblab intentionally will not approve or merge these PRs for you. There should always be human review to ensure the SDK changes match your expectations. Some suggestions for checks are:

  1. Validate any added or removed endpoints are what you are expecting from your API updates.
  2. Check the SDK version. If your API changes would lead to breaking changes in the generated SDK, you should bump the SDK version. This version is set by you in the config file.
  3. Check any updates to the package manifest files (such as package.json or pyproject.toml) and the README. If you want to manually edit these files, or have additions that might be overwritten by the SDK generation process, you can ignore these files in the SDK generation process by adding them to the config file.

Once you are happy with the changes you can merge the PR. If you need to update your API spec, or liblab config file and regenerate the SDK you can close the PR and delete the branch. liblab will create a new branch and PR the next time you run the command.