CLI Tools

The Skara command-line interface (CLI) tools enables a CLI driven workflow where reviews are made either via the mailing lists or in an web browser using an external Git source code hosting provider's web application. The following CLI tools are currently available as part of project Skara:

• git-jcheck - a backwards compatible Git port of jcheck

• git-webrev - a backwards compatible Git port of webrev

• git-defpath - a backwards compatible Git port of defpath

• git-fork - fork a project on an external Git source code hosting provider to your personal space and optionally clone it

• git-sync - sync the personal fork of the project with the current state of the upstream repository

• git-pr - interact with pull requests for a project on an external Git source code hosting provider

• git-info - show OpenJDK information about commits, e.g. issue links, authors, contributors, etc.

• git-token - interact with a Git credential manager for handling personal access tokens

• git-translate - translate between Mercurial and Git hashes

• git-publish - publish a local branch to a remote repository
• git-proxy - proxy all network traffic from a Git command through a HTTP(S) proxy

• git-skara - learn about and update the Skara CLI tool

All above CLI tools support multiple external Git source code hosting providers.

Table of Contents

Installing

To install the Skara tooling, simply clone the Skara repository and include the Skara Git configuration file:

$ git clone https://github.com/openjdk/skara
$ git config --global include.path "$PWD/skara/skara.gitconfig"

The Skara tooling will bootstrap itself the first time you use any of the Skara commands. To check that everything works run git skara help:

$ git skara help

Note: if your computer is behind a HTTP(S) proxy, ensure that you have set the HTTPS_PROXY environment variable correctly.

Updating

To update the Skara tooling run git skara update:

$ git skara update

The update command pull eventual updates and rebuild the tooling if necessary. Note: if your computer is behind a HTTP(S) proxy, ensure that you have set the HTTPS_PROXY environment variable correctly.

Personal Access Token

Some of the Skara tools requires a personal access token (PAT) to authenticate against an external Git source code hosting provider's API. A personal access token is a like a password that has limited capabilities, it can only be used to successfully authenticate and perform certain limited actions. The following Skara tools requires a personal access token:

• git-fork
• git-pr
• git-token

Note: if you do not intend to use the above tools, then there is no need to set up a personal access token and you can skip this section. All the other tools described in the beginning of this document works fine without a personal access token. If you do wish to make use of the above three tools, then please read on.

Configuring a personal access token consists of two steps:

1. Set up a credential manager for securely storing the personal access token locally on your computer
2. Generate the personal access token and store it in the credential manager

The way to carry out the above two steps differs depending on the operating system you use, please follow the instructions below suitable for your operating system.

Windows

Credential Manager

If you installed Git via Git for Windows then you already have a credential manager from Microsoft installed (it is bundled with Git for Windows). If you installed Git via some other mechanism, then you must first install Microsoft's Git Credential Manager for Windows.

Personal Access Token

To generate a a personal access token on GitHub go to https://github.com/settings/tokens and and click on "Generate new token". You only need to select the "repo" scope (permission). After you have generated your personal access token, store it in the Git Credential Manager for Windows using git token store:

> git token store https://github.com
Username: <insert your Github username>
Password: <insert your "Personal Access Token", not your GitHub password>

macOS

Credential Manager

macOS already comes with a password manager in the form of Keychain and Git for macOS is configured out of the box to use Keychain as a credential manager, there is no need to configure anything.

Personal Access Token

To generate a a personal access token on GitHub go to https://github.com/settings/tokens and and click on "Generate new token". You only need to select the "repo" scope (permission). After you have generated your personal access token, store it in Keychain using git token store:

$ git token store https://github.com
Username: <insert your Github username>
Password: <insert your "Personal Access Token", not your GitHub password>

GNU/Linux

The credential manager you will use on GNU/Linux to the personal access token depends on your desktop environment. If you are using a desktop environment with support for GNOME Keyring, then follow the instructions in the GNOME Keyring section. If you are using a GNU/Linux installation without a desktop environment (e.g. when using SSH to connect to a server) or a desktop environment that does not support the GNOME Keyring (e.g. XFCE, KDE, i3), then you need to pick a credential manager that suits your security and usability needs. The following sections will present four common choices for storing personal access tokens when you are unable to use GNOME Keyring:

• GPG
• age
• pass
• plain files

GNOME Keyring

Credential Manager

On GNU/Linux installations that features the GNOME Keyring the recommended setup is to use libsecret and the "libsecret credential helper" in order to use GNOME Keyring as the credential manager Please follow the instructions for setting up libsecret for the GNU/Linux distribution you are using.

Fedora

Fedora 30, 31 and 32 comes with libsecret and GNOME Keyring installed by default. When you install the git package you also get the libsecret credential helper automatically installed. To configure git to use the libsecret credential helper run the following command:

$ git config --global credential.helper /usr/libexec/git-core/git-credential-libsecret

If you want to have a graphical utility to inspect the GNOME Keyring we recommend that you install GNOME Seahorse:

sudo dnf install seahorse

Ubuntu

Ubuntu 19.10 and 18.04.4 (LTS) comes with libsecret and GNOME Keyring installed by default. Unfortunately even if you install the Git package you will not get a binary version of the libsecret credential helper installed (you only get the source). This means you have to compile the libsecret credential helper yourself. Compile the libsecret credential with the following two commands:

$ sudo apt install libsecret-1-dev
$ sudo make --directory=/usr/share/doc/git/contrib/credential/libsecret

Once you have compiled the libsecret credential helper you must configure Git to use it:

$ git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret

If you want to have a graphical utility to inspect the GNOME Keyring we recommend that you install GNOME Seahorse:

$ sudo apt install seahorse

Personal Access Token

To generate a a Personal Access Token on GitHub go to https://github.com/settings/tokens and and click on "Generate new token". You only need to select the "repo" scope (permission). After you have generated your token, store it in the GNOME Keyring using git token store:

$ git token store https://github.com
Username: <insert your Github username>
Password: <insert your "Personal Access Token", not your GitHub password>

Other

If you are using an environment or distribution without support for GNOME Keyring (for example if you are connecting to a GNU/Linux server over SSH), or if you want to use your own scheme for storing the PAT, then that is also supported. You can store non-sensitive data such as your username and the URL of the Git source code hosting provider in your ~/.gitconfig file in the "credential" section:

[credential "https://github.com"]
username = YOUR-GITHUB-USERNAME

For the PAT itself, all Skara tools interacting with an external Git source code hosting provider's API supports the GIT_TOKEN environment variable. This means that instead of storing your PAT in a secure way in a Git credential manager you will have to secure the PAT yourself according to your security requirements. To generate a a Personal Access Token on GitHub go to https://github.com/settings/tokens and and click on "Generate new token". You only need to select the "repo" scope (permission). The following sections then give a few examples on how to securely store the PAT you just generated depending your security needs.

GPG

You can use GnuPG (GPG) to store your PAT in an encrypted file. The file can be encrypted either using a GPG key or using a passphrase. If you have a GPG key you probably already know how to encrypt a file with it, so we will only cover encrypting using a passphrase here. To encrypt the PAT in a file using a passphrase, run the following command (replacing <PAT> with your personal access token):

$ echo '<PAT>' | gpg --symmetric -o ~/pat.gpg
Enter passphrase:
Repeat passphrase:

When using applicable Skara CLI tools set the GIT_TOKEN environment variable to the decrypted value, for example:

GIT_TOKEN=$(gpg --decrypt ~/pat.gpg) git pr list

age

You can use age to store you PAT in an encrypted file. To encrypt the file using a passphrase, run the following command (replacing <PAT> with your personal access token):

$ echo '<PAT>' | age --passphrase > ~/pat.age 

When using applicable Skara CLI tools set the GIT_TOKEN environment variable to the decrypted value, for example:

$ GIT_TOKEN=$(age --decrypt ~/pat.age) git pr list

File Permissions

A non-secure way to restrict access to your PAT is to store it in plain-text but accessible read-only to the current user. To store your PAT, run the following commands (replacing <PAT> with your personal access token):

$ echo '<PAT>' > ~/pat.txt
$ chmod 0400 ~/pat.txt

When using applicable Skara CLI tools set the GIT_TOKEN environment variable:

$ GIT_TOKEN=$(cat ~/pat.txt) git pr list

Using

Creating a personal fork

The first step in the Skara workflow is to create a personal fork of an existing OpenJDK repository. To create personal fork

$ git fork https://github.com/openjdk/<REPO>

For example, to create a personal fork of the jdk repository, run:

$ git fork https://github.com/openjdk/jdk

The above command git fork will also clone your personal fork to a local repository on your computer.

Creating a pull request

To create a pull request first create a personal fork, then create a local branch in the local clone of your personal fork:

$ git checkout -b JDK-8123456

Do your work and then create a commit:

$ git commit -m "Fixed a race condition"

Finally create your pull request:

$ git pr create --jcheck --publish