gerrit

package
v0.0.0-...-1643519 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2024 License: Apache-2.0 Imports: 18 Imported by: 2

Documentation

Index

Constants

View Source 
const OAuthScope = "https://www.googleapis.com/auth/gerritcodereview"

OAuthScope is the OAuth 2.0 scope that must be included when acquiring an access token for Gerrit RPCs.

Variables

View Source 
var (
	RevisionRework                 RevisionKind = "REWORK"
	RevisionTrivialRebase                       = "TRIVIAL_REBASE"
	RevisionMergeFirstParentUpdate              = "MERGE_FIRST_PARENT_UPDATE"
	RevisionNoCodeChange                        = "NO_CODE_CHANGE"
	RevisionNoChange                            = "NO_CHANGE"
)

Functions

func NewRESTClient 

func NewRESTClient(httpClient *http.Client, host string, auth bool) (gerritpb.GerritClient, error)

NewRESTClient creates a new Gerrit client based on Gerrit's REST API.

The host must be a full Gerrit host, e.g. "chromium-review.googlesource.com".

If auth is true, indicates that the given HTTP client sends authenticated requests. If so, the requests to Gerrit will include "/a/" URL path prefix.

RPC methods of the returned client return an error if a grpc.CallOption is passed.

func NormalizeGerritURL 

func NormalizeGerritURL(gerritURL string) (string, error)

NormalizeGerritURL returns canonical for Gerrit URL.

error is returned if validation fails.

func ValidateGerritURL 

func ValidateGerritURL(gerritURL string) error

ValidateGerritURL validates Gerrit URL for use in this package.

Types

type AbandonInput 

type AbandonInput struct {
	// Message to be added as review comment to the change when abandoning it.
	Message string `json:"message,omitempty"`

	// Notify is an enum specifying whom to send notifications to.
	//
	// Valid values are NONE, OWNER, OWNER_REVIEWERS, and ALL.
	//
	// Optional. The default is ALL.
	Notify string `json:"notify,omitempty"`
}

AbandonInput contains information for abandoning a change.

This struct is intended to be one-to-one with the AbandonInput structure described in Gerrit's documentation: https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#abandon-input

TODO(mknyszek): Support notify_details.

type AccountInfo 

type AccountInfo struct {
	// AccountID is the numeric ID of the account managed by Gerrit, and is guaranteed to
	// be unique.
	AccountID int `json:"_account_id,omitempty"`

	// Name is the full name of the user.
	Name string `json:"name,omitempty"`

	// Email is the email address the user prefers to be contacted through.
	Email string `json:"email,omitempty"`

	// SecondaryEmails is a list of secondary email addresses of the user.
	SecondaryEmails []string `json:"secondary_emails,omitempty"`

	// Username is the username of the user.
	Username string `json:"username,omitempty"`

	// MoreAccounts represents whether the query would deliver more results if not limited.
	// Only set on the last account that is returned.
	MoreAccounts bool `json:"_more_accounts,omitempty"`
}

AccountInfo contains information about an account.

type AddReviewerResult 

type AddReviewerResult struct {
	// Input is the value of the `reviewer` field from ReviewerInput set while adding the reviewer.
	Input string `json:"input"`

	// Reviewers is a list of newly added reviewers.
	Reviewers []ReviewerInfo `json:"reviewers,omitempty"`

	// CCs is a list of newly CCed accounts. This field will only appear if the requested `state`
	// for the reviewer was CC and NoteDb is enabled on the server.
	CCs []ReviewerInfo `json:"ccs,omitempty"`

	// Error is a message explaining why the reviewer could not be added.
	//
	// If a group was specified in the input and an error is returned, that means none of the
	// members were added as reviewer.
	Error string `json:"error,omitempty"`

	// Confirm represents whether adding the reviewer requires confirmation.
	Confirm bool `json:"confirm,omitempty"`
}

AddReviewerResult describes the result of adding a reviewer to a change.

type Change 

type Change struct {
	ChangeNumber           int                     `json:"_number"`
	ID                     string                  `json:"id"`
	ChangeID               string                  `json:"change_id"`
	Project                string                  `json:"project"`
	Branch                 string                  `json:"branch"`
	Topic                  string                  `json:"topic"`
	Hashtags               []string                `json:"hashtags"`
	Subject                string                  `json:"subject"`
	Status                 string                  `json:"status"`
	Created                string                  `json:"created"`
	Updated                string                  `json:"updated"`
	Mergeable              bool                    `json:"mergeable"`
	Submitted              string                  `json:"submitted"`
	SubmitType             string                  `json:"submit_type"`
	Insertions             int                     `json:"insertions"`
	Deletions              int                     `json:"deletions"`
	UnresolvedCommentCount int                     `json:"unresolved_comment_count"`
	HasReviewStarted       bool                    `json:"has_review_started"`
	Owner                  AccountInfo             `json:"owner"`
	Labels                 map[string]LabelInfo    `json:"labels"`
	Submitter              AccountInfo             `json:"submitter"`
	Reviewers              Reviewers               `json:"reviewers"`
	RevertOf               int                     `json:"revert_of"`
	CurrentRevision        string                  `json:"current_revision"`
	Revisions              map[string]RevisionInfo `json:"revisions"`
	// MoreChanges is not part of a Change, but gerrit piggy-backs on the
	// last Change in a page to set this flag if there are more changes
	// in the results of a query.
	MoreChanges bool `json:"_more_changes"`
}

Change represents a Gerrit CL. Information about these fields in: https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-info

Note that not all fields will be filled for all CLs and queries depending on query options, and not all fields exposed by Gerrit are captured by this struct. Adding more fields to this struct should be okay (but only Gerrit-supported keys will be populated).

TODO(nodir): replace this type with https://godoc.org/go.chromium.org/luci/common/proto/gerrit#ChangeInfo.

type ChangeDetailsParams 

type ChangeDetailsParams struct {
	// Options is a set of optional details to add as additional fieldsof the response.
	// These require additional database searches and may delay the response.
	//
	// The supported strings for options are listed in Gerrit's api
	// documentation at the link below:
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes
	Options []string `json:"o"`
}

ChangeDetailsParams contains optional parameters for getting change details from Gerrit.

type ChangeInput 

type ChangeInput struct {
	// Project is the name of the project for this change.
	Project string `json:"project"`

	// Branch is the name of the target branch for this change.
	// refs/heads/ prefix is omitted.
	Branch string `json:"branch"`

	// Subject is the header line of the commit message.
	Subject string `json:"subject"`

	// Topic is the topic to which this change belongs. Optional.
	Topic string `json:"topic,omitempty"`

	// IsPrivate sets whether the change is marked private.
	IsPrivate bool `json:"is_private,omitempty"`

	// WorkInProgress sets the work-in-progress bit for the change.
	WorkInProgress bool `json:"work_in_progress,omitempty"`

	// BaseChange is the change this new change is based on. Optional.
	//
	// This can be anything Gerrit expects as a ChangeID. We recommend <numericId>,
	// but the full list of supported formats can be found here:
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id
	BaseChange string `json:"base_change,omitempty"`

	// NewBranch allows for creating a new branch when set to true.
	NewBranch bool `json:"new_branch,omitempty"`

	// Notify is an enum specifying whom to send notifications to.
	//
	// Valid values are NONE, OWNER, OWNER_REVIEWERS, and ALL.
	//
	// Optional. The default is ALL.
	Notify string `json:"notify,omitempty"`
}

ChangeInput contains the parameters necesary for creating a change in Gerrit.

This struct is intended to be one-to-one with the ChangeInput structure described in Gerrit's documentation: https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-input

The exception is only status, which is always "NEW" and is therefore unavailable in this struct.

TODO(mknyszek): Support merge and notify_details.

type ChangeQueryParams 

type ChangeQueryParams struct {
	// Actual query string, see
	// https://gerrit-review.googlesource.com/Documentation/user-search.html#_search_operators
	Query string `json:"q"`
	// How many changes to include in the response.
	N int `json:"n"`
	// Skip this many from the list of results (unreliable for paging).
	S int `json:"S"`
	// Include these options in the queries. Certain options will make
	// Gerrit fill in additional fields of the response. These require
	// additional database searches and may delay the response.
	//
	// The supported strings for options are listed in Gerrit's api
	// documentation at the link below:
	// https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes
	Options []string `json:"o"`
}

ChangeQueryParams contains the parameters necessary for querying changes from Gerrit.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a production Gerrit client, instantiated via NewClient(), and uses an http.Client along with a validated url to communicate with Gerrit.

func NewClient 

func NewClient(c *http.Client, gerritURL string) (*Client, error)

NewClient creates a new instance of Client and validates and stores the URL to reach Gerrit. The result is wrapped inside a Client so that the apis can be called directly on the value returned by this function.

func (*Client) AbandonChange 

func (c *Client) AbandonChange(ctx context.Context, changeID string, ai *AbandonInput) (*Change, error)

AbandonChange abandons an existing change in Gerrit.

Returns a Change referenced by changeID, with status ABANDONED, if abandoned.

AbandonInput is optional (that is, may be nil).

The changeID parameter may be in any of the forms supported by Gerrit:

  • "4247"
  • "I8473b95934b5732ac55d26311a706c9c2bde9940"
  • etc. See the link below.

https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id

func (*Client) ChangeDetails 

func (c *Client) ChangeDetails(ctx context.Context, changeID string, options ChangeDetailsParams) (*Change, error)

ChangeDetails gets details about a single change with optional fields.

This method returns a single *Change and an error.

The changeID parameter may be in any of the forms supported by Gerrit:

  • "4247"
  • "I8473b95934b5732ac55d26311a706c9c2bde9940"
  • etc. See the link below.

https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id

options is a list of strings like {"CURRENT_REVISION"} which tells Gerrit to return non-default properties for Change. The supported strings for options are listed in Gerrit's api documentation at the link below: https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes

func (*Client) ChangeQuery 

func (c *Client) ChangeQuery(ctx context.Context, qr ChangeQueryParams) ([]*Change, bool, error)

ChangeQuery returns a list of Gerrit changes for a given ChangeQueryParams.

One example use case for this is getting the CL for a given commit hash. Only the .Query property of the qr parameter is required.

Returns a slice of Change, whether there are more changes to fetch and an error.

func (*Client) CreateChange 

func (c *Client) CreateChange(ctx context.Context, ci *ChangeInput) (*Change, error)

CreateChange creates a new change in Gerrit.

Returns a Change describing the newly created change or an error.

func (*Client) IsChangePureRevert 

func (c *Client) IsChangePureRevert(ctx context.Context, changeID string) (bool, error)

IsChangePureRevert determines if a change is a pure revert of another commit.

This method returns a bool and an error.

To determine which commit the change is purportedly reverting, use the revert_of property of the change.

Gerrit's doc for the api: https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#get-pure-revert

func (*Client) SetReview 

func (c *Client) SetReview(ctx context.Context, changeID string, revisionID string, ri *ReviewInput) (*ReviewResult, error)

SetReview sets a review on a revision, optionally also publishing draft comments, setting labels, adding reviewers or CCs, and modifying the work in progress property.

Returns a ReviewResult which describes the applied labels and any added reviewers.

The changeID parameter may be in any of the forms supported by Gerrit:

  • "4247"
  • "I8473b95934b5732ac55d26311a706c9c2bde9940"
  • etc. See the link below.

https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id

The revisionID parameter may be in any of the forms supported by Gerrit:

  • "current"
  • a commit ID
  • "0" or the literal "edit" for a change edit
  • etc. See the link below.

https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#revision-id

type LabelInfo 

type LabelInfo struct {
	// Optional reflects whether the label is optional (neither necessary
	// for nor blocking submission).
	Optional bool `json:"optional,omitempty"`

	// Approved refers to one user who approved this label (max value).
	Approved *AccountInfo `json:"approved,omitempty"`

	// Rejected refers to one user who rejected this label (min value).
	Rejected *AccountInfo `json:"rejected,omitempty"`

	// Recommended refers to one user who recommended this label (positive
	// value, but not max).
	Recommended *AccountInfo `json:"recommended,omitempty"`

	// Disliked refers to one user who disliked this label (negative value
	// but not min).
	Disliked *AccountInfo `json:"disliked,omitempty"`

	// Blocking reflects whether this label block the submit operation.
	Blocking bool `json:"blocking,omitempty"`
}

LabelInfo contains information about a label on a change, always corresponding to the current patch set.

Only one of Approved, Rejected, Recommended, and Disliked will be set, with priority Rejected > Approved > Recommened > Disliked if multiple users have given the label different values.

TODO(mknyszek): Support 'value' and 'default_value' fields, as well as the fields given with the query parameter DETAILED_LABELS.

type ReviewInput 

type ReviewInput struct {
	// Message is the message to be added as a review comment.
	Message string `json:"message,omitempty"`

	// Tag represents a tag to apply to review comment messages, votes, and inline comments.
	//
	// Tags may be used by CI or other automated systems to distinguish them from human
	// reviews.
	Tag string `json:"tag,omitempty"`

	// Labels represents the votes that should be added to the revision as a map of label names
	// to voting values.
	Labels map[string]int `json:"labels,omitempty"`

	// Notify is an enum specifying whom to send notifications to.
	//
	// Valid values are NONE, OWNER, OWNER_REVIEWERS, and ALL.
	//
	// Optional. The default is ALL.
	Notify string `json:"notify,omitempty"`

	// OnBehalfOf is an account-id which the review should be posted on behalf of.
	//
	// To use this option the caller must have granted labelAs-NAME permission for all keys
	// of labels.
	//
	// More information on account-id may be found here:
	// https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#account-id
	OnBehalfOf string `json:"on_behalf_of,omitempty"`

	// Reviewers is a list of ReviewerInput representing reviewers that should be added to the change. Optional.
	Reviewers []ReviewerInput `json:"reviewers,omitempty"`

	// Ready, if set to true, will move the change from WIP to ready to review if possible.
	//
	// It is an error for both Ready and WorkInProgress to be true.
	Ready bool `json:"ready,omitempty"`

	// WorkInProgress sets the work-in-progress bit for the change.
	//
	// It is an error for both Ready and WorkInProgress to be true.
	WorkInProgress bool `json:"work_in_progress,omitempty"`
}

ReviewInput contains information for adding a review to a revision.

TODO(mknyszek): Add support for comments, robot_comments, drafts, notify, and omit_duplicate_comments.

type ReviewResult 

type ReviewResult struct {
	// Labels is a map of labels to values after the review was posted.
	//
	// nil if any reviewer additions were rejected.
	Labels map[string]int `json:"labels,omitempty"`

	// Reviewers is a map of accounts or group identifiers to an AddReviewerResult representing
	// the outcome of adding the reviewer.
	//
	// Absent if no reviewer additions were requested.
	Reviewers map[string]AddReviewerResult `json:"reviewers,omitempty"`

	// Ready marks if the change was moved from WIP to ready for review as a result of this action.
	Ready bool `json:"ready,omitempty"`
}

ReviewResult contains information regarding the updates that were made to a review.

type ReviewerInfo 

type ReviewerInfo struct {
	AccountInfo

	// Approvals maps label names to the approval values given by this reviewer.
	Approvals map[string]string `json:"approvals,omitempty"`
}

ReviewerInfo contains information about a reviewer and their votes on a change.

It has the same fields as AccountInfo, except the AccountID is optional if an unregistered reviewer was added.

type ReviewerInput 

type ReviewerInput struct {
	// Reviewer is an account-id that should be added as a reviewer, or a group-id for which
	// all members should be added as reviewers. If Reviewer identifies both an account and a
	// group, only the account is added as a reviewer to the change.
	//
	// More information on account-id may be found here:
	// https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#account-id
	//
	// More information on group-id may be found here:
	// https://gerrit-review.googlesource.com/Documentation/rest-api-groups.html#group-id
	Reviewer string `json:"reviewer"`

	// State is the state in which to add the reviewer. Possible reviewer states are REVIEWER
	// and CC. If not given, defaults to REVIEWER.
	State string `json:"state,omitempty"`

	// Confirmed represents whether adding the reviewer is confirmed.
	//
	// The Gerrit server may be configured to require a confirmation when adding a group as
	// a reviewer that has many members.
	Confirmed bool `json:"confirmed"`

	// Notify is an enum specifying whom to send notifications to.
	//
	// Valid values are NONE, OWNER, OWNER_REVIEWERS, and ALL.
	//
	// Optional. The default is ALL.
	Notify string `json:"notify,omitempty"`
}

ReviewerInput contians information for adding a reviewer to a change.

TODO(mknyszek): Add support for notify_details.

type Reviewers 

type Reviewers struct {
	CC       []AccountInfo `json:"CC"`
	Reviewer []AccountInfo `json:"REVIEWER"`
	Removed  []AccountInfo `json:"REMOVED"`
}

Reviewers is a map that maps a type of reviewer to its account info.

type RevisionInfo 

type RevisionInfo struct {
	// PatchSetNumber is the number associated with the given patch set.
	PatchSetNumber int `json:"_number"`

	// Kind is the kind of revision this is.
	//
	// Allowed values are specified in the RevisionKind type.
	Kind RevisionKind `json:"kind"`

	// Ref is the Git reference for the patchset.
	Ref string `json:"ref"`

	// Uploader represents the account which uploaded this patch set.
	Uploader AccountInfo `json:"uploader"`
}

RevisionInfo contains information about a specific patch set.

Corresponds with https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#revision-info. TODO(mknyszek): Support the rest of that structure.

type RevisionKind 

type RevisionKind string

RevisionKind represents the "kind" field for a patch set.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.