go-gerrit

go-gerrit is a Go client library for the Gerrit Code Review system.

Features

• Authentication (HTTP Basic, HTTP Digest, HTTP Cookie)
• Every API Endpoint like Gerrit
  • /access/
  • /accounts/
  • /changes/
  • /config/
  • /groups/
  • /plugins/
  • /projects/
• Supports optional plugin APIs such as
  • events-log - About, REST API

Installation

go-gerrit follows the Go Release Policy. This means we support the current + 2 previous Go versions.

It is go gettable ...

$ go get github.com/andygrunwald/go-gerrit

API / Usage

Have a look at the GoDoc documentation for a detailed API description.

The Gerrit Code Review - REST API was the foundation document.

Authentication

Gerrit supports multiple ways for authentication.

HTTP Basic

Some Gerrit instances (like TYPO3) has auth.gitBasicAuth activated. With this, you can authenticate with HTTP Basic like this:

instance := "https://review.typo3.org/"
client, _ := gerrit.NewClient(instance, nil)
client.Authentication.SetBasicAuth("andy.grunwald", "my secrect password")

self, _, _ := client.Accounts.GetAccount("self")

fmt.Printf("Username: %s", self.Name)

// Username: Andy Grunwald

If you get a 401 Unauthorized, check your Account Settings and have a look at the HTTP Password configuration.

HTTP Digest

Some Gerrit instances (like Wikimedia) has Digest access authentication activated.

instance := "https://gerrit.wikimedia.org/r/"
client, _ := gerrit.NewClient(instance, nil)
client.Authentication.SetDigestAuth("andy.grunwald", "my secrect http password")

self, resp, err := client.Accounts.GetAccount("self")

fmt.Printf("Username: %s", self.Name)

// Username: Andy Grunwald

If the chosen Gerrit instance does not support digest auth, an error like WWW-Authenticate header type is not Digest is thrown.

If you get a 401 Unauthorized, check your Account Settings and have a look at the HTTP Password configuration.

HTTP Cookie

Some Gerrit instances hosted like the one hosted googlesource.com (e.g. Go, Android or Gerrit) support HTTP Cookie authentication.

You need the cookie name and the cookie value. You can get them by click on "Settings > HTTP Password > Obtain Password" in your Gerrit instance.

There you can receive your values. The cookie name will be (mostly) o (if hosted on googlesource.com). Your cookie secret will be something like git-your@email.com=SomeHash....

instance := "https://gerrit-review.googlesource.com/"
client, _ := gerrit.NewClient(instance, nil)
client.Authentication.SetCookieAuth("o", "my-cookie-secret")

self, _, _ := client.Accounts.GetAccount("self")

fmt.Printf("Username: %s", self.Name)

// Username: Andy G.

Examples

More examples are available

• in the GoDoc examples section.
• in the examples folder

Get version of Gerrit instance

Receive the version of the Gerrit instance used by the Gerrit team for development:

package main

import (
	"fmt"

	"github.com/andygrunwald/go-gerrit"
)

func main() {
	instance := "https://gerrit-review.googlesource.com/"
	client, err := gerrit.NewClient(instance, nil)
	if err != nil {
		panic(err)
	}

	v, _, err := client.Config.GetVersion()
	if err != nil {
		panic(err)
	}

	fmt.Printf("Version: %s", v)

	// Version: 3.4.1-2066-g8db5605430
}

Get all public projects

List all projects from Chromium:

package main

import (
	"fmt"

	"github.com/andygrunwald/go-gerrit"
)

func main() {
	instance := "https://chromium-review.googlesource.com/"
	client, err := gerrit.NewClient(instance, nil)
	if err != nil {
		panic(err)
	}

	opt := &gerrit.ProjectOptions{
		Description: true,
	}
	projects, _, err := client.Projects.ListProjects(opt)
	if err != nil {
		panic(err)
	}

	for name, p := range *projects {
		fmt.Printf("%s - State: %s\n", name, p.State)
	}

	// chromiumos/third_party/bluez - State: ACTIVE
	// external/github.com/Polymer/ShadowDOM - State: ACTIVE
	// external/github.com/domokit/mojo_sdk - State: ACTIVE
	// ...
}

Query changes

Get some changes of the kernel/common project from the AndroidGerrit Review System.

package main

import (
	"fmt"

	"github.com/andygrunwald/go-gerrit"
)

func main() {
	instance := "https://android-review.googlesource.com/"
	client, err := gerrit.NewClient(instance, nil)
	if err != nil {
		panic(err)
	}

	opt := &gerrit.QueryChangeOptions{}
	opt.Query = []string{"project:kernel/common"}
	opt.AdditionalFields = []string{"LABELS"}
	changes, _, err := client.Changes.QueryChanges(opt)
	if err != nil {
		panic(err)
	}

	for _, change := range *changes {
		fmt.Printf("Project: %s -> %s -> %s%d\n", change.Project, change.Subject, instance, change.Number)
	}

	// Project: kernel/common -> ANDROID: GKI: Update symbols to symbol list -> https://android-review.googlesource.com/1830553
	// Project: kernel/common -> ANDROID: db845c_gki.fragment: Remove CONFIG_USB_NET_AX8817X from fragment -> https://android-review.googlesource.com/1830439
	// Project: kernel/common -> ANDROID: Update the ABI representation -> https://android-review.googlesource.com/1830469
	// ...
}

Development

Running tests and linters

Tests only:

$ make test

Checks, tests and linters

$ make vet staticcheck test

Local Gerrit setup

For local development, we suggest the usage of the official Gerrit Code Review docker image:

$ docker run -ti -p 8080:8080 -p 29418:29418 gerritcodereview/gerrit:3.4.1

Wait a few minutes until the Gerrit Code Review NNN ready message appears, where NNN is your current Gerrit version, then open your browser to https://localhost:8080 and you will be in Gerrit Code Review.

Authentication

For local development setups, go to https://localhost:8080/settings/#HTTPCredentials and click GENERATE NEW PASSWORD. Now you can use (only for development purposes):

client.Authentication.SetBasicAuth("admin", "secret")

Replace secret with your new value.

Frequently Asked Questions (FAQ)

How is the source code organized?

The source code organization is inspired by go-github by Google.

Every REST API Endpoint (e.g. /access/, /changes/) is coupled in a service (e.g. AccessService in access.go, ChangesService in changes.go). Every service is part of gerrit.Client as a member variable.

gerrit.Client can provide essential helper functions to avoid unnecessary code duplications, such as building a new request or parse responses.

Based on this structure, implementing a new API functionality is straight forward. Here is an example of *ChangeService.DeleteTopic* / DELETE /changes/{change-id}/topic:

func (s *ChangesService) DeleteTopic(changeID string) (*Response, error) {
    u := fmt.Sprintf("changes/%s/topic", changeID)
    return s.client.DeleteRequest(u, nil)
}

What about the version compatibility with Gerrit?

The library was implemented based on the REST API of Gerrit version 2.11.3-1230-gb8336f1 and tested against this version.

This library might be working with older versions as well. If you notice an incompatibility open a new issue. We also appreciate your Pull Requests to improve this library. We welcome contributions!

What about adding code to support the REST API of an (optional) plugin?

It will depend on the plugin, and you are welcome to open a new issue first to propose the idea and use-case. As an example, the addition of support for events-log plugin was supported because the plugin itself is fairly popular. The structures that the REST API uses could also be used by gerrit stream-events.

License

This project is released under the terms of the MIT license.