Lab - Gitlab utility

An overview of the gitlab lab utility and how to use it to perform basic contributor and reviewer actions on the command line with Red Hat kernels hosted on GitLab. Bugs and feature requests for the lab utility can be filed at https://github.com/zaquestion/lab/issues.

Scope

Readers are assumed to have knowledge of git, the GitLab workflow, and the RHEL kernel development process.

The code examples below are based on the author’s use of the lab utility. You must replace occurrences of ‘prarit’ with your own username in all command line examples below. The examples also assume that an ssh key has been configured for use with GitLab.

Readers will recognize that many ‘lab’ commands are wrappers around standard git commands. For example the ‘lab clone’ is a wrapper around ‘git clone’. This behaviour is planned to change in a few releases.

Installing and configuring the ‘lab’ Utility

The user may choose between installing a pre-built RPM package or by building it manually.

RPM installation

The RPM package is available in a COPR repo. Users must enable the rhkernel-devtools repository to use it through dnf:

	dnf copr enable -y bmeneguele/rhkernel-devtools

Users can now install the lab tool using the default package by executing:

	dnf install -y lab

Note: RHEL and Fedora users may have different versions of the lab tool. Fedora packages may get upgraded to pre-release versions, while RHEL packages will always point to the latest stable version.

Packaging bugs can be reported by opening up issues at https://gitlab.com/ptalbert/rhkernel-devtools.

Manual build

Users must install usr/bin/go on their systems before building ‘lab’. Users can build ‘lab’ by executing,

	git clone https://github.com/zaquestion/lab.git
	cd lab
	make

The ‘make’ command will take some time as go package dependencies are resolved. After completion, move the lab command to somewhere in your $PATH, and then change directories before attempting to configure lab.

Configuration

To configure lab, simply execute

lab

and the utility will query for configuration information. The first query will be for the default GitLab host. For the RHEL, CentOS, and ARK projects select the default of 'https://gitlab.com' by hitting the Enter key.

Enter GitLab host (default: https://gitlab.com):

The next step is to enter a GitLab Personal Access Token (PAT):

Create a token with scope 'api' here: https://gitlab.com/profile/personal_access_tokens
Enter default GitLab token, or leave blank to provide a command to load the token:

At this step you can enter the token as hidden text, or leave the entry to use a password manager (ex. Bitwarded, pass, lastpass, etc.). If left blank, lab will request the password manager command to retrieve the token

Enter command to load the token:

If all is successful, the configuration will complete with a

Config saved to ~/.config/lab/lab.toml

message. This configuration file is the global lab configuration file written in toml. The format was chosen for its similarity to git configuration files.

Troubleshooting lab

Was lab installed from COPR? In general, users are encouraged to use the version in COPR.
Are you sure your Personal Access Token (PAT) is for scope “API”? lab requires a PAT of scope “API”. If you plan to use HTTPS protocol, then the PAT must also have “read_repository” and “write_repository” scopes set.
Does ~/.config/lab/lab.toml contain your host, user, and PAT? If the file does not contain entries for the host, user, and PAT, delete the file and try the configuration again. A correct file may look as follows:

~$ cat .config/lab/lab.toml

[core]
  host = "https://gitlab.com"
  token = "sj-184annNGsgoobelgooq"
  user = "myuser"
~$

I see an error similar to

2021/01/14 13:50:19 [DEBUG] GEThttps://gitlab.com/api/v4/user[ ]https://gitlab.com/api/v4/user
2021/01/14 13:50:20 config.go:195: GEThttps://gitlab.com/api/v4/user[ ]https://gitlab.com/api/v4/user: 401 {message: 401 Unauthorized}
Error: User authentication failed. This is likely due to a misconfigured Personal Access Token. Verify the token or token_load config settings before attempting to authenticate.

Check that ~/.config/lab/lab.toml contains entries for the host, user, and PAT, and make sure that you are executing in a gitlab repository.

I see strange strings like ^{[]11;rgb:dddd/dddd/dddd}G or ^{[]11;rgb:fdfd/f6f6/e3e3}G at the beginning and the end of output of lab commands.

These were resolved in an upstream commit after version 0.19. Please upgrade to the
latest version of lab.

Lab bugs can be reported by opening up issues at https://github.com/zaquestion/lab/issues

Developer Actions

The common developer actions are forking a project, cloning a project, creating a branch, pushing a branch, and creating a merge request. Users can verify project access by executing

	lab project list --member

Forking a Project

A project can be forked by executing

	git clone git@gitlab.com:redhat/rhel/src/kernel/kernel-test
	# The above command will fail if you have insufficient permissions for the project.
	# See link:https://documentation-debarbos-f8e912a6a47526aa0f0c78469340fa6e8a9fd095.gitlab.io/docs/rh_and_gitlab_configuration.html[Red Hat and GitLab Configuration] for information.
	cd kernel-test
	lab fork  # fork located at https://gitlab.com/_prarit_/kernel-test

The fork process is the same process used on the gitlab webUI to create a fork. The kernel has a large codebase and the fork command may take some time to complete. In general, forks are created in the user’s namespaces as https://gitlab.com/<username>/<project_name>;.

Cloning a Forked Project

A project can be cloned by executing a clone command on your resulting fork. For example,

	git clone git@gitlab.com:_prarit_/kernel-test.git

Cloning the project will result in a different remote structure than forking a project. It is recommended you execute

	git remote add _prarit_ git@gitlab.com:_prarit_/kernel-test.git
	git remote remove origin
	git remote add origin git@gitlab.com:redhat/rhel/src/kernel/kernel-test.git

so that the resulting remotes are (as seen with ‘git remote -v’),

           origin  git@gitlab.com:redhat/rhel/src/kernel/kernel-test.git (fetch)
           origin  git@gitlab.com:redhat/rhel/src/kernel/kernel-test.git (push)
           prarit  git@gitlab.com:prarit/kernel-test.git (fetch)
           prarit  git@gitlab.com:prarit/kernel-test.git (push)

Alternatively you can name origin as ‘upstream’. If you choose to do that please replace ‘origin’ with ‘upstream’ below.

Users should note that the lab utility special cases ‘upstream’ and ‘origin’ as remotes. If you choose another name for the upstream/origin remote you must execute ‘git push -u <remote>’ to appropriately set the upstream remote.

Creating a branch and modifying code

Branches can be created by executing

	git checkout -b <branch_name>
	# make some changes to code
	git commit -s <files>

	git branch <branch_name>
	git checkout <branch_name>
	# make some changes to code
	git commit -s <files>

Creating a Merge Request on gitlab

There are two methods that can be used to create a merge request. The first method uses ‘lab push’ to directly create the merge request, and the second is a two-step process to push the branch to origin, and then separately creating the merge request. Both can be completed on the command line using ‘lab’.

Single Step Merge Request

To create a merge request in one command, execute

	git push -o merge_request.create -o merge_request.remove_source_branch -u _prarit_ <branch_name>

or, to create merge request that targets a specific branch, execute

	git push -o merge_request.create -o merge_request.remove_source_branch -o merge_request.target=<target_branch_name> -u _prarit_ <branch_name>

Two Step Merge Request

To create a merge request, execute

	git checkout <branch_name>
	git push _prarit_ <branch_name> # in some cases this may be ‘git push -u’
	lab mr create origin # this must be executed on <branch_name>

The third command, ‘lab mr create’ will open a $GIT_EDITOR window and provide an opportunity to change your merge request description and verify the actions you are making. This is one of the reasons the two step merge request process may be preferable to users submitting multi-commit merge requests.

To open a merge request against a specific remote branch, the ‘lab mr create’ command can be replaced with

	lab mr create origin <remote_branch_name>

The submitted merge request can be viewed by executing

	lab mr list # shows a list of merge requests +
	lab mr show <merge_request_id>

Modifying a Merge Request

Merge requests can be modified on the command line. For example, to send a new changeset version execute

	git checkout <branch_name>
	# make code changes
	git commit -s <files>
	git push -f _prarit_ <branch_name>

Rebasing a branch

Branches can be rebased using git. A typical action is to rebase a branch against the latest upstream main branch:

	git fetch origin
	git rebase origin/main

Reviewer Actions

The common reviewer actions are checking out the merge request code for review, viewing a merge request’s comments, and adding comments to a merge request.

Checking out a Merge Request

A merge request can be easily checked out into a local tree by executing

	lab mr list # shows a list of merge requests
	lab mr checkout <merge_request_id>

Patches for review can be generated by executing the usual git command,

	git-format-patches -number_of_patches

Viewing a Merge Request (and comments)

A merge request can be viewed by executing

	lab mr show <merge_request_id>

or, to see the merge request and it’s comments,

	lab mr show <merge_request_id> --comments

Adding Comments to a Merge Request

To add a comment to a merge request, execute

	lab mr note <merge_request_id>

This command will open a $GIT_EDITOR window and allow a reviewer to add comments to the merge request (Comments on the code, Acked-by:, Nacked-by:, etc.).

Avoiding GitLab Namespace Collisions

It is possible that two projects have the same name. For example, project one could be https://gitlab.com/prarit/kernel-test, and another project could be https://gitlab.com/bmeneg/kernel-test. A user forking these projects into their namespace would end up with a collison on the name ‘kernel-test’. A user can avoid this problem by forking the project with a new name by executing

	lab fork <upstream project> -n <fork_name>

In addition, lab also provides the option for the user to fork the upstream project to a different namespace (group), allowing the projects with the same name to live in different namespaces, similar to how the upstream repositories are organized. For example, an upstream project can be forked into a group by executing

	lab fork <upstream project> -g <group_name>

Configuring lab command options

Lab command options can be configured globally for all GitLab trees, or locally for each GitLab tree. For example, adding

[mr_list]
  all = true

to ~/.config/lab/lab.toml will add --all to every execution of the ‘lab mr list’ command on a user’s system. Adding the same entry to the local .gitconfig/lab.toml will only add --all to every execution of the ‘lab mr list’ command in that specific tree.

lab options are explained in lab’s README.md.

Example with kernel-ark git tree

The above instructions surround the use of the RHEL kernel trees. The lab CLI can be used with other trees, for example, with the kernel-ark tree.

Users should follow the the kernel-ark configuration instructions at https://gitlab.com/cki-project/kernel-ark/-/wikis/home, so that the remotes are configured as

origin    git@gitlab.com:prarit/kernel-ark.git (fetch)
origin    git@gitlab.com:prarit/kernel-ark.git (push)
upstream    git@gitlab.com:cki-project/kernel-ark.git (fetch)
upstream    git@gitlab.com:cki-project/kernel-ark.git (push)

To create a merge request a user would do

	git checkout -b <branch_name>
	# make changes
	git commit <files>
	git push origin <branch_name> # push branch to fork
	lab mr create upstream # must be executed on branch_name

Example: Submitting v2 of a changeset

This example is based on the kernel-ark configuration instructions at https://gitlab.com/cki-project/kernel-ark/-/wikis/home, so that the remotes are configured as

origin    git@gitlab.com:prarit/kernel-ark.git (fetch)
origin    git@gitlab.com:prarit/kernel-ark.git (push)
upstream    git@gitlab.com:cki-project/kernel-ark.git (fetch)
upstream    git@gitlab.com:cki-project/kernel-ark.git (push)

To submit a new version of a changeset, a user would do

	git checkout -b <existing_branch_name>
	# make changes
	git fetch upstream
	git rebase upstream/main # this may cause an interactive rebase
	# make changes
	git push -f origin <existing_branch_name>