Skip to main content

Pull request 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 branches and 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 LIBLAB_GITHUB_TOKEN, This token should be scoped to just the SDK repos that you want to raise PRs in, and needs the following repository permissions.

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:
    • Verify that the GitHub organization is correctly set in the liblab config file
    • Check that your access 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 access 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 GitHub repo name is correct in the liblab config file options for that language.

The PR creation process​

You can create a PR using the liblab pr command, combined with the LIBLAB_GITHUB_TOKEN environment variable. You can run this locally to test the process, but it is designed to be run in your CI/CD pipeline.

The PR creation process is as follows:

  1. A new branch is created in the repo with a unique name, based off the target branch. By default this is the main branch, but you can override this using the targetBranch setting. 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. By default this PR will be against the main branch, but you can override this using the targetBranch setting.
note

The PR that is created will be against main by default unless you specify another branch.

When you create your SDK repo, you need to create the main branch - this is not created by default when you create a new repo in GitHub unless you add files such as a README, LICENSE or .gitignore.

If you see this error:

Default branch: main does not exists in the repository

Then check that you have created the main branch in your repo.

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.

Last updated on