github-plugin/src/main/resources/Documentation/config.md

GitHub configuration during Gerrit init

This plugin provides a customized Gerrit init step for the self-configuration of the main GitHub and Gerrit authentication settings for allowing the github-oauth library to work properly.

GitHub OAuth library rely on Gerrit HTTP authentication defined during the standard Gerrit init steps. See below a sample session of relevant init steps for a default configuration pointing to the Web GitHub instance:

   *** GitHub Integration
   *** 

   GitHub URL                     [https://github.com]: 
   GitHub API URL                 [https://api.github.com]: 

   NOTE: You might need to configure a proxy using http.proxy if you run Gerrit behind a firewall.

   *** GitHub OAuth registration and credentials
   *** 

   Register Gerrit as GitHub application on:
   https://github.com/settings/applications/new

   Settings (assumed Gerrit URL: http://localhost:8080/)
   * Application name: Gerrit Code Review
   * Homepage URL: http://localhost:8080/
   * Authorization callback URL: http://localhost:8080/oauth

   After registration is complete, enter the generated OAuth credentials:
   GitHub Client ID               [1ebea047915210179cf5]: 
   ClientSecret                   []: f82c3f9b3802666f2adcc4c8cacfb164295b0a99
   confirm password : 
   HTTP Authentication Header     [GITHUB_USER]:

Configuration

GitHub plugin read his configuration from gerrit.config under the [github] section.

github.url : GitHub homepage URL. Default is https://github.com. Can be customized to a different value for GitHub:Enterprise integration

NOTE You might need to configure a proxy using the configuration http.proxy if you run Gerrit behind a firewall.

github.apiUrl : GitHub API URL. Default is https://api.github.com. Can be customized to a different value for GitHub:Enterprise integration

github.clientId : The Client ID, that was received from GitHub when the application was registered. Required.

github.clientSecret : The Client Secret, that was received from GitHub when the application was registered. Required.

github.scopes : The GitHub scopes for allowing access to the user's public or private profile, organisations and repositories. See GitHub Scopes definition for a detailed description of available scopes and their associated permissions. Default is empty read-only access to public information (includes public user profile info, public repository info, and gists).

github.httpConnectionTimeout : Maximum time to wait for GitHub API to answer to a new HTTP connection attempt. Values should use common common unit unit suffixes to express their setting: * ms, milliseconds * s, sec, second, seconds * m, min, minute, minutes * h, hr, hour, hours Default value: 30 seconds

github.httpReadTimeout : Maximum time to wait for GitHub API to respond or send data over an existing HTTP connection. Values should use common common unit unit suffixes to express their setting: * ms, milliseconds * s, sec, second, seconds * m, min, minute, minutes * h, hr, hour, hours Default value: 30 seconds

Key Configuration

Since this plugin obtains credentials from Github and persists them in Gerrit, it also takes care of encrypting them at rest. The Gerrit admin can configure how this is done by setting the relevant configuration parameters.

github-key..passwordDevice : The device or file where to retrieve the encryption passphrase.
Default: /dev/zero

NOTE: such configuration is considered insecure and should not be used in production, always set a non-zero password device for deriving the key.

github-key..passwordLength : The length in bytes of the password read from the passwordDevice.
Default: 16

github-key..cipherAlgorithm : The algorithm to be used for encryption/decryption. Available algorithms are described in the Cipher section of the Java Cryptography Architecture Standard Algorithm Name Documentation.
Default: AES/ECB/PKCS5Padding

github-key..secretKeyAlgorithm : the algorithm to be used to encrypt the provided password. Available algorithms are described in the Cipher section of the Java Cryptography Architecture Standard Algorithm Name Documentation.
Default: AES

github-key..current : Whether this configuration is the current one, and it should be used to encrypt new Github credentials. Note that exactly one github-key configuration must be set to current, otherwise an error exception will be thrown.
Default: false

As you can observe, in order to support key rotations, multiple github-key can be specified in configuration. credentials encrypted with a <key-id> key can still be decrypted as long as the github-key.<key-id> stanza is available in the configuration. New credentials will always be encrypted with the current <key-id>.

Note that unencrypted oauth tokens will be handled gracefully and just passed through to github by the decryption algorithm. This is done so that oauth tokens that were persisted before the encryption feature was implemented will still be considered valid until their natural expiration time.

If no github-key.<key-id> exists in configuration, then a default current key configuration (named current) will be inferred, using the defaults documented above.

NOTE such configuration is considered insecure and should not be used in production.