pulls.go

Documentation: github.com/google/go-github/v55/github

     1  // Copyright 2013 The go-github AUTHORS. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  package github
     7  
     8  import (
     9  	"bytes"
    10  	"context"
    11  	"fmt"
    12  )
    13  
    14  // PullRequestsService handles communication with the pull request related
    15  // methods of the GitHub API.
    16  //
    17  // GitHub API docs: https://docs.github.com/en/rest/pulls/
    18  type PullRequestsService service
    19  
    20  // PullRequestAutoMerge represents the "auto_merge" response for a PullRequest.
    21  type PullRequestAutoMerge struct {
    22  	EnabledBy     *User   `json:"enabled_by,omitempty"`
    23  	MergeMethod   *string `json:"merge_method,omitempty"`
    24  	CommitTitle   *string `json:"commit_title,omitempty"`
    25  	CommitMessage *string `json:"commit_message,omitempty"`
    26  }
    27  
    28  // PullRequest represents a GitHub pull request on a repository.
    29  type PullRequest struct {
    30  	ID                  *int64                `json:"id,omitempty"`
    31  	Number              *int                  `json:"number,omitempty"`
    32  	State               *string               `json:"state,omitempty"`
    33  	Locked              *bool                 `json:"locked,omitempty"`
    34  	Title               *string               `json:"title,omitempty"`
    35  	Body                *string               `json:"body,omitempty"`
    36  	CreatedAt           *Timestamp            `json:"created_at,omitempty"`
    37  	UpdatedAt           *Timestamp            `json:"updated_at,omitempty"`
    38  	ClosedAt            *Timestamp            `json:"closed_at,omitempty"`
    39  	MergedAt            *Timestamp            `json:"merged_at,omitempty"`
    40  	Labels              []*Label              `json:"labels,omitempty"`
    41  	User                *User                 `json:"user,omitempty"`
    42  	Draft               *bool                 `json:"draft,omitempty"`
    43  	Merged              *bool                 `json:"merged,omitempty"`
    44  	Mergeable           *bool                 `json:"mergeable,omitempty"`
    45  	MergeableState      *string               `json:"mergeable_state,omitempty"`
    46  	MergedBy            *User                 `json:"merged_by,omitempty"`
    47  	MergeCommitSHA      *string               `json:"merge_commit_sha,omitempty"`
    48  	Rebaseable          *bool                 `json:"rebaseable,omitempty"`
    49  	Comments            *int                  `json:"comments,omitempty"`
    50  	Commits             *int                  `json:"commits,omitempty"`
    51  	Additions           *int                  `json:"additions,omitempty"`
    52  	Deletions           *int                  `json:"deletions,omitempty"`
    53  	ChangedFiles        *int                  `json:"changed_files,omitempty"`
    54  	URL                 *string               `json:"url,omitempty"`
    55  	HTMLURL             *string               `json:"html_url,omitempty"`
    56  	IssueURL            *string               `json:"issue_url,omitempty"`
    57  	StatusesURL         *string               `json:"statuses_url,omitempty"`
    58  	DiffURL             *string               `json:"diff_url,omitempty"`
    59  	PatchURL            *string               `json:"patch_url,omitempty"`
    60  	CommitsURL          *string               `json:"commits_url,omitempty"`
    61  	CommentsURL         *string               `json:"comments_url,omitempty"`
    62  	ReviewCommentsURL   *string               `json:"review_comments_url,omitempty"`
    63  	ReviewCommentURL    *string               `json:"review_comment_url,omitempty"`
    64  	ReviewComments      *int                  `json:"review_comments,omitempty"`
    65  	Assignee            *User                 `json:"assignee,omitempty"`
    66  	Assignees           []*User               `json:"assignees,omitempty"`
    67  	Milestone           *Milestone            `json:"milestone,omitempty"`
    68  	MaintainerCanModify *bool                 `json:"maintainer_can_modify,omitempty"`
    69  	AuthorAssociation   *string               `json:"author_association,omitempty"`
    70  	NodeID              *string               `json:"node_id,omitempty"`
    71  	RequestedReviewers  []*User               `json:"requested_reviewers,omitempty"`
    72  	AutoMerge           *PullRequestAutoMerge `json:"auto_merge,omitempty"`
    73  
    74  	// RequestedTeams is populated as part of the PullRequestEvent.
    75  	// See, https://docs.github.com/en/developers/webhooks-and-events/github-event-types#pullrequestevent for an example.
    76  	RequestedTeams []*Team `json:"requested_teams,omitempty"`
    77  
    78  	Links *PRLinks           `json:"_links,omitempty"`
    79  	Head  *PullRequestBranch `json:"head,omitempty"`
    80  	Base  *PullRequestBranch `json:"base,omitempty"`
    81  
    82  	// ActiveLockReason is populated only when LockReason is provided while locking the pull request.
    83  	// Possible values are: "off-topic", "too heated", "resolved", and "spam".
    84  	ActiveLockReason *string `json:"active_lock_reason,omitempty"`
    85  }
    86  
    87  func (p PullRequest) String() string {
    88  	return Stringify(p)
    89  }
    90  
    91  // PRLink represents a single link object from GitHub pull request _links.
    92  type PRLink struct {
    93  	HRef *string `json:"href,omitempty"`
    94  }
    95  
    96  // PRLinks represents the "_links" object in a GitHub pull request.
    97  type PRLinks struct {
    98  	Self           *PRLink `json:"self,omitempty"`
    99  	HTML           *PRLink `json:"html,omitempty"`
   100  	Issue          *PRLink `json:"issue,omitempty"`
   101  	Comments       *PRLink `json:"comments,omitempty"`
   102  	ReviewComments *PRLink `json:"review_comments,omitempty"`
   103  	ReviewComment  *PRLink `json:"review_comment,omitempty"`
   104  	Commits        *PRLink `json:"commits,omitempty"`
   105  	Statuses       *PRLink `json:"statuses,omitempty"`
   106  }
   107  
   108  // PullRequestBranch represents a base or head branch in a GitHub pull request.
   109  type PullRequestBranch struct {
   110  	Label *string     `json:"label,omitempty"`
   111  	Ref   *string     `json:"ref,omitempty"`
   112  	SHA   *string     `json:"sha,omitempty"`
   113  	Repo  *Repository `json:"repo,omitempty"`
   114  	User  *User       `json:"user,omitempty"`
   115  }
   116  
   117  // PullRequestListOptions specifies the optional parameters to the
   118  // PullRequestsService.List method.
   119  type PullRequestListOptions struct {
   120  	// State filters pull requests based on their state. Possible values are:
   121  	// open, closed, all. Default is "open".
   122  	State string `url:"state,omitempty"`
   123  
   124  	// Head filters pull requests by head user and branch name in the format of:
   125  	// "user:ref-name".
   126  	Head string `url:"head,omitempty"`
   127  
   128  	// Base filters pull requests by base branch name.
   129  	Base string `url:"base,omitempty"`
   130  
   131  	// Sort specifies how to sort pull requests. Possible values are: created,
   132  	// updated, popularity, long-running. Default is "created".
   133  	Sort string `url:"sort,omitempty"`
   134  
   135  	// Direction in which to sort pull requests. Possible values are: asc, desc.
   136  	// If Sort is "created" or not specified, Default is "desc", otherwise Default
   137  	// is "asc"
   138  	Direction string `url:"direction,omitempty"`
   139  
   140  	ListOptions
   141  }
   142  
   143  // List the pull requests for the specified repository.
   144  //
   145  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#list-pull-requests
   146  func (s *PullRequestsService) List(ctx context.Context, owner string, repo string, opts *PullRequestListOptions) ([]*PullRequest, *Response, error) {
   147  	u := fmt.Sprintf("repos/%v/%v/pulls", owner, repo)
   148  	u, err := addOptions(u, opts)
   149  	if err != nil {
   150  		return nil, nil, err
   151  	}
   152  
   153  	req, err := s.client.NewRequest("GET", u, nil)
   154  	if err != nil {
   155  		return nil, nil, err
   156  	}
   157  
   158  	var pulls []*PullRequest
   159  	resp, err := s.client.Do(ctx, req, &pulls)
   160  	if err != nil {
   161  		return nil, resp, err
   162  	}
   163  
   164  	return pulls, resp, nil
   165  }
   166  
   167  // ListPullRequestsWithCommit returns pull requests associated with a commit SHA.
   168  //
   169  // The results may include open and closed pull requests.
   170  // By default, the PullRequestListOptions State filters for "open".
   171  //
   172  // GitHub API docs: https://docs.github.com/en/rest/commits/commits#list-pull-requests-associated-with-a-commit
   173  func (s *PullRequestsService) ListPullRequestsWithCommit(ctx context.Context, owner, repo, sha string, opts *ListOptions) ([]*PullRequest, *Response, error) {
   174  	u := fmt.Sprintf("repos/%v/%v/commits/%v/pulls", owner, repo, sha)
   175  	u, err := addOptions(u, opts)
   176  	if err != nil {
   177  		return nil, nil, err
   178  	}
   179  
   180  	req, err := s.client.NewRequest("GET", u, nil)
   181  	if err != nil {
   182  		return nil, nil, err
   183  	}
   184  
   185  	// TODO: remove custom Accept header when this API fully launches.
   186  	req.Header.Set("Accept", mediaTypeListPullsOrBranchesForCommitPreview)
   187  	var pulls []*PullRequest
   188  	resp, err := s.client.Do(ctx, req, &pulls)
   189  	if err != nil {
   190  		return nil, resp, err
   191  	}
   192  
   193  	return pulls, resp, nil
   194  }
   195  
   196  // Get a single pull request.
   197  //
   198  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request
   199  func (s *PullRequestsService) Get(ctx context.Context, owner string, repo string, number int) (*PullRequest, *Response, error) {
   200  	u := fmt.Sprintf("repos/%v/%v/pulls/%d", owner, repo, number)
   201  	req, err := s.client.NewRequest("GET", u, nil)
   202  	if err != nil {
   203  		return nil, nil, err
   204  	}
   205  
   206  	pull := new(PullRequest)
   207  	resp, err := s.client.Do(ctx, req, pull)
   208  	if err != nil {
   209  		return nil, resp, err
   210  	}
   211  
   212  	return pull, resp, nil
   213  }
   214  
   215  // GetRaw gets a single pull request in raw (diff or patch) format.
   216  //
   217  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request
   218  func (s *PullRequestsService) GetRaw(ctx context.Context, owner string, repo string, number int, opts RawOptions) (string, *Response, error) {
   219  	u := fmt.Sprintf("repos/%v/%v/pulls/%d", owner, repo, number)
   220  	req, err := s.client.NewRequest("GET", u, nil)
   221  	if err != nil {
   222  		return "", nil, err
   223  	}
   224  
   225  	switch opts.Type {
   226  	case Diff:
   227  		req.Header.Set("Accept", mediaTypeV3Diff)
   228  	case Patch:
   229  		req.Header.Set("Accept", mediaTypeV3Patch)
   230  	default:
   231  		return "", nil, fmt.Errorf("unsupported raw type %d", opts.Type)
   232  	}
   233  
   234  	var buf bytes.Buffer
   235  	resp, err := s.client.Do(ctx, req, &buf)
   236  	if err != nil {
   237  		return "", resp, err
   238  	}
   239  
   240  	return buf.String(), resp, nil
   241  }
   242  
   243  // NewPullRequest represents a new pull request to be created.
   244  type NewPullRequest struct {
   245  	Title               *string `json:"title,omitempty"`
   246  	Head                *string `json:"head,omitempty"`
   247  	HeadRepo            *string `json:"head_repo,omitempty"`
   248  	Base                *string `json:"base,omitempty"`
   249  	Body                *string `json:"body,omitempty"`
   250  	Issue               *int    `json:"issue,omitempty"`
   251  	MaintainerCanModify *bool   `json:"maintainer_can_modify,omitempty"`
   252  	Draft               *bool   `json:"draft,omitempty"`
   253  }
   254  
   255  // Create a new pull request on the specified repository.
   256  //
   257  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#create-a-pull-request
   258  func (s *PullRequestsService) Create(ctx context.Context, owner string, repo string, pull *NewPullRequest) (*PullRequest, *Response, error) {
   259  	u := fmt.Sprintf("repos/%v/%v/pulls", owner, repo)
   260  	req, err := s.client.NewRequest("POST", u, pull)
   261  	if err != nil {
   262  		return nil, nil, err
   263  	}
   264  
   265  	p := new(PullRequest)
   266  	resp, err := s.client.Do(ctx, req, p)
   267  	if err != nil {
   268  		return nil, resp, err
   269  	}
   270  
   271  	return p, resp, nil
   272  }
   273  
   274  // PullRequestBranchUpdateOptions specifies the optional parameters to the
   275  // PullRequestsService.UpdateBranch method.
   276  type PullRequestBranchUpdateOptions struct {
   277  	// ExpectedHeadSHA specifies the most recent commit on the pull request's branch.
   278  	// Default value is the SHA of the pull request's current HEAD ref.
   279  	ExpectedHeadSHA *string `json:"expected_head_sha,omitempty"`
   280  }
   281  
   282  // PullRequestBranchUpdateResponse specifies the response of pull request branch update.
   283  type PullRequestBranchUpdateResponse struct {
   284  	Message *string `json:"message,omitempty"`
   285  	URL     *string `json:"url,omitempty"`
   286  }
   287  
   288  // UpdateBranch updates the pull request branch with latest upstream changes.
   289  //
   290  // This method might return an AcceptedError and a status code of
   291  // 202. This is because this is the status that GitHub returns to signify that
   292  // it has now scheduled the update of the pull request branch in a background task.
   293  // A follow up request, after a delay of a second or so, should result
   294  // in a successful request.
   295  //
   296  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#update-a-pull-request-branch
   297  func (s *PullRequestsService) UpdateBranch(ctx context.Context, owner, repo string, number int, opts *PullRequestBranchUpdateOptions) (*PullRequestBranchUpdateResponse, *Response, error) {
   298  	u := fmt.Sprintf("repos/%v/%v/pulls/%d/update-branch", owner, repo, number)
   299  
   300  	req, err := s.client.NewRequest("PUT", u, opts)
   301  	if err != nil {
   302  		return nil, nil, err
   303  	}
   304  
   305  	// TODO: remove custom Accept header when this API fully launches.
   306  	req.Header.Set("Accept", mediaTypeUpdatePullRequestBranchPreview)
   307  
   308  	p := new(PullRequestBranchUpdateResponse)
   309  	resp, err := s.client.Do(ctx, req, p)
   310  	if err != nil {
   311  		return nil, resp, err
   312  	}
   313  
   314  	return p, resp, nil
   315  }
   316  
   317  type pullRequestUpdate struct {
   318  	Title               *string `json:"title,omitempty"`
   319  	Body                *string `json:"body,omitempty"`
   320  	State               *string `json:"state,omitempty"`
   321  	Base                *string `json:"base,omitempty"`
   322  	MaintainerCanModify *bool   `json:"maintainer_can_modify,omitempty"`
   323  }
   324  
   325  // Edit a pull request.
   326  // pull must not be nil.
   327  //
   328  // The following fields are editable: Title, Body, State, Base.Ref and MaintainerCanModify.
   329  // Base.Ref updates the base branch of the pull request.
   330  //
   331  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#update-a-pull-request
   332  func (s *PullRequestsService) Edit(ctx context.Context, owner string, repo string, number int, pull *PullRequest) (*PullRequest, *Response, error) {
   333  	if pull == nil {
   334  		return nil, nil, fmt.Errorf("pull must be provided")
   335  	}
   336  
   337  	u := fmt.Sprintf("repos/%v/%v/pulls/%d", owner, repo, number)
   338  
   339  	update := &pullRequestUpdate{
   340  		Title:               pull.Title,
   341  		Body:                pull.Body,
   342  		State:               pull.State,
   343  		MaintainerCanModify: pull.MaintainerCanModify,
   344  	}
   345  	// avoid updating the base branch when closing the Pull Request
   346  	// - otherwise the GitHub API server returns a "Validation Failed" error:
   347  	// "Cannot change base branch of closed pull request".
   348  	if pull.Base != nil && pull.GetState() != "closed" {
   349  		update.Base = pull.Base.Ref
   350  	}
   351  
   352  	req, err := s.client.NewRequest("PATCH", u, update)
   353  	if err != nil {
   354  		return nil, nil, err
   355  	}
   356  
   357  	p := new(PullRequest)
   358  	resp, err := s.client.Do(ctx, req, p)
   359  	if err != nil {
   360  		return nil, resp, err
   361  	}
   362  
   363  	return p, resp, nil
   364  }
   365  
   366  // ListCommits lists the commits in a pull request.
   367  //
   368  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#list-commits-on-a-pull-request
   369  func (s *PullRequestsService) ListCommits(ctx context.Context, owner string, repo string, number int, opts *ListOptions) ([]*RepositoryCommit, *Response, error) {
   370  	u := fmt.Sprintf("repos/%v/%v/pulls/%d/commits", owner, repo, number)
   371  	u, err := addOptions(u, opts)
   372  	if err != nil {
   373  		return nil, nil, err
   374  	}
   375  
   376  	req, err := s.client.NewRequest("GET", u, nil)
   377  	if err != nil {
   378  		return nil, nil, err
   379  	}
   380  
   381  	var commits []*RepositoryCommit
   382  	resp, err := s.client.Do(ctx, req, &commits)
   383  	if err != nil {
   384  		return nil, resp, err
   385  	}
   386  
   387  	return commits, resp, nil
   388  }
   389  
   390  // ListFiles lists the files in a pull request.
   391  //
   392  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#list-pull-requests-files
   393  func (s *PullRequestsService) ListFiles(ctx context.Context, owner string, repo string, number int, opts *ListOptions) ([]*CommitFile, *Response, error) {
   394  	u := fmt.Sprintf("repos/%v/%v/pulls/%d/files", owner, repo, number)
   395  	u, err := addOptions(u, opts)
   396  	if err != nil {
   397  		return nil, nil, err
   398  	}
   399  
   400  	req, err := s.client.NewRequest("GET", u, nil)
   401  	if err != nil {
   402  		return nil, nil, err
   403  	}
   404  
   405  	var commitFiles []*CommitFile
   406  	resp, err := s.client.Do(ctx, req, &commitFiles)
   407  	if err != nil {
   408  		return nil, resp, err
   409  	}
   410  
   411  	return commitFiles, resp, nil
   412  }
   413  
   414  // IsMerged checks if a pull request has been merged.
   415  //
   416  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#check-if-a-pull-request-has-been-merged
   417  func (s *PullRequestsService) IsMerged(ctx context.Context, owner string, repo string, number int) (bool, *Response, error) {
   418  	u := fmt.Sprintf("repos/%v/%v/pulls/%d/merge", owner, repo, number)
   419  	req, err := s.client.NewRequest("GET", u, nil)
   420  	if err != nil {
   421  		return false, nil, err
   422  	}
   423  
   424  	resp, err := s.client.Do(ctx, req, nil)
   425  	merged, err := parseBoolResponse(err)
   426  	return merged, resp, err
   427  }
   428  
   429  // PullRequestMergeResult represents the result of merging a pull request.
   430  type PullRequestMergeResult struct {
   431  	SHA     *string `json:"sha,omitempty"`
   432  	Merged  *bool   `json:"merged,omitempty"`
   433  	Message *string `json:"message,omitempty"`
   434  }
   435  
   436  // PullRequestOptions lets you define how a pull request will be merged.
   437  type PullRequestOptions struct {
   438  	CommitTitle string // Title for the automatic commit message. (Optional.)
   439  	SHA         string // SHA that pull request head must match to allow merge. (Optional.)
   440  
   441  	// The merge method to use. Possible values include: "merge", "squash", and "rebase" with the default being merge. (Optional.)
   442  	MergeMethod string
   443  
   444  	// If false, an empty string commit message will use the default commit message. If true, an empty string commit message will be used.
   445  	DontDefaultIfBlank bool
   446  }
   447  
   448  type pullRequestMergeRequest struct {
   449  	CommitMessage *string `json:"commit_message,omitempty"`
   450  	CommitTitle   string  `json:"commit_title,omitempty"`
   451  	MergeMethod   string  `json:"merge_method,omitempty"`
   452  	SHA           string  `json:"sha,omitempty"`
   453  }
   454  
   455  // Merge a pull request.
   456  // commitMessage is an extra detail to append to automatic commit message.
   457  //
   458  // GitHub API docs: https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request
   459  func (s *PullRequestsService) Merge(ctx context.Context, owner string, repo string, number int, commitMessage string, options *PullRequestOptions) (*PullRequestMergeResult, *Response, error) {
   460  	u := fmt.Sprintf("repos/%v/%v/pulls/%d/merge", owner, repo, number)
   461  
   462  	pullRequestBody := &pullRequestMergeRequest{}
   463  	if commitMessage != "" {
   464  		pullRequestBody.CommitMessage = &commitMessage
   465  	}
   466  	if options != nil {
   467  		pullRequestBody.CommitTitle = options.CommitTitle
   468  		pullRequestBody.MergeMethod = options.MergeMethod
   469  		pullRequestBody.SHA = options.SHA
   470  		if options.DontDefaultIfBlank && commitMessage == "" {
   471  			pullRequestBody.CommitMessage = &commitMessage
   472  		}
   473  	}
   474  	req, err := s.client.NewRequest("PUT", u, pullRequestBody)
   475  	if err != nil {
   476  		return nil, nil, err
   477  	}
   478  
   479  	mergeResult := new(PullRequestMergeResult)
   480  	resp, err := s.client.Do(ctx, req, mergeResult)
   481  	if err != nil {
   482  		return nil, resp, err
   483  	}
   484  
   485  	return mergeResult, resp, nil
   486  }
   487
View as plain text