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 6package github 7 8import ( 9 "context" 10 "fmt" 11 "time" 12) 13 14// IssuesService handles communication with the issue related 15// methods of the GitHub API. 16// 17// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/ 18type IssuesService service 19 20// Issue represents a GitHub issue on a repository. 21// 22// Note: As far as the GitHub API is concerned, every pull request is an issue, 23// but not every issue is a pull request. Some endpoints, events, and webhooks 24// may also return pull requests via this struct. If PullRequestLinks is nil, 25// this is an issue, and if PullRequestLinks is not nil, this is a pull request. 26// The IsPullRequest helper method can be used to check that. 27type Issue struct { 28 ID *int64 `json:"id,omitempty"` 29 Number *int `json:"number,omitempty"` 30 State *string `json:"state,omitempty"` 31 Locked *bool `json:"locked,omitempty"` 32 Title *string `json:"title,omitempty"` 33 Body *string `json:"body,omitempty"` 34 AuthorAssociation *string `json:"author_association,omitempty"` 35 User *User `json:"user,omitempty"` 36 Labels []*Label `json:"labels,omitempty"` 37 Assignee *User `json:"assignee,omitempty"` 38 Comments *int `json:"comments,omitempty"` 39 ClosedAt *time.Time `json:"closed_at,omitempty"` 40 CreatedAt *time.Time `json:"created_at,omitempty"` 41 UpdatedAt *time.Time `json:"updated_at,omitempty"` 42 ClosedBy *User `json:"closed_by,omitempty"` 43 URL *string `json:"url,omitempty"` 44 HTMLURL *string `json:"html_url,omitempty"` 45 CommentsURL *string `json:"comments_url,omitempty"` 46 EventsURL *string `json:"events_url,omitempty"` 47 LabelsURL *string `json:"labels_url,omitempty"` 48 RepositoryURL *string `json:"repository_url,omitempty"` 49 Milestone *Milestone `json:"milestone,omitempty"` 50 PullRequestLinks *PullRequestLinks `json:"pull_request,omitempty"` 51 Repository *Repository `json:"repository,omitempty"` 52 Reactions *Reactions `json:"reactions,omitempty"` 53 Assignees []*User `json:"assignees,omitempty"` 54 NodeID *string `json:"node_id,omitempty"` 55 56 // TextMatches is only populated from search results that request text matches 57 // See: search.go and https://docs.github.com/en/free-pro-team@latest/rest/reference/search/#text-match-metadata 58 TextMatches []*TextMatch `json:"text_matches,omitempty"` 59 60 // ActiveLockReason is populated only when LockReason is provided while locking the issue. 61 // Possible values are: "off-topic", "too heated", "resolved", and "spam". 62 ActiveLockReason *string `json:"active_lock_reason,omitempty"` 63} 64 65func (i Issue) String() string { 66 return Stringify(i) 67} 68 69// IsPullRequest reports whether the issue is also a pull request. It uses the 70// method recommended by GitHub's API documentation, which is to check whether 71// PullRequestLinks is non-nil. 72func (i Issue) IsPullRequest() bool { 73 return i.PullRequestLinks != nil 74} 75 76// IssueRequest represents a request to create/edit an issue. 77// It is separate from Issue above because otherwise Labels 78// and Assignee fail to serialize to the correct JSON. 79type IssueRequest struct { 80 Title *string `json:"title,omitempty"` 81 Body *string `json:"body,omitempty"` 82 Labels *[]string `json:"labels,omitempty"` 83 Assignee *string `json:"assignee,omitempty"` 84 State *string `json:"state,omitempty"` 85 Milestone *int `json:"milestone,omitempty"` 86 Assignees *[]string `json:"assignees,omitempty"` 87} 88 89// IssueListOptions specifies the optional parameters to the IssuesService.List 90// and IssuesService.ListByOrg methods. 91type IssueListOptions struct { 92 // Filter specifies which issues to list. Possible values are: assigned, 93 // created, mentioned, subscribed, all. Default is "assigned". 94 Filter string `url:"filter,omitempty"` 95 96 // State filters issues based on their state. Possible values are: open, 97 // closed, all. Default is "open". 98 State string `url:"state,omitempty"` 99 100 // Labels filters issues based on their label. 101 Labels []string `url:"labels,comma,omitempty"` 102 103 // Sort specifies how to sort issues. Possible values are: created, updated, 104 // and comments. Default value is "created". 105 Sort string `url:"sort,omitempty"` 106 107 // Direction in which to sort issues. Possible values are: asc, desc. 108 // Default is "desc". 109 Direction string `url:"direction,omitempty"` 110 111 // Since filters issues by time. 112 Since time.Time `url:"since,omitempty"` 113 114 ListOptions 115} 116 117// PullRequestLinks object is added to the Issue object when it's an issue included 118// in the IssueCommentEvent webhook payload, if the webhook is fired by a comment on a PR. 119type PullRequestLinks struct { 120 URL *string `json:"url,omitempty"` 121 HTMLURL *string `json:"html_url,omitempty"` 122 DiffURL *string `json:"diff_url,omitempty"` 123 PatchURL *string `json:"patch_url,omitempty"` 124} 125 126// List the issues for the authenticated user. If all is true, list issues 127// across all the user's visible repositories including owned, member, and 128// organization repositories; if false, list only owned and member 129// repositories. 130// 131// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#list-user-account-issues-assigned-to-the-authenticated-user 132// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#list-issues-assigned-to-the-authenticated-user 133func (s *IssuesService) List(ctx context.Context, all bool, opts *IssueListOptions) ([]*Issue, *Response, error) { 134 var u string 135 if all { 136 u = "issues" 137 } else { 138 u = "user/issues" 139 } 140 return s.listIssues(ctx, u, opts) 141} 142 143// ListByOrg fetches the issues in the specified organization for the 144// authenticated user. 145// 146// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#list-organization-issues-assigned-to-the-authenticated-user 147func (s *IssuesService) ListByOrg(ctx context.Context, org string, opts *IssueListOptions) ([]*Issue, *Response, error) { 148 u := fmt.Sprintf("orgs/%v/issues", org) 149 return s.listIssues(ctx, u, opts) 150} 151 152func (s *IssuesService) listIssues(ctx context.Context, u string, opts *IssueListOptions) ([]*Issue, *Response, error) { 153 u, err := addOptions(u, opts) 154 if err != nil { 155 return nil, nil, err 156 } 157 158 req, err := s.client.NewRequest("GET", u, nil) 159 if err != nil { 160 return nil, nil, err 161 } 162 163 // TODO: remove custom Accept header when this API fully launch. 164 req.Header.Set("Accept", mediaTypeReactionsPreview) 165 166 var issues []*Issue 167 resp, err := s.client.Do(ctx, req, &issues) 168 if err != nil { 169 return nil, resp, err 170 } 171 172 return issues, resp, nil 173} 174 175// IssueListByRepoOptions specifies the optional parameters to the 176// IssuesService.ListByRepo method. 177type IssueListByRepoOptions struct { 178 // Milestone limits issues for the specified milestone. Possible values are 179 // a milestone number, "none" for issues with no milestone, "*" for issues 180 // with any milestone. 181 Milestone string `url:"milestone,omitempty"` 182 183 // State filters issues based on their state. Possible values are: open, 184 // closed, all. Default is "open". 185 State string `url:"state,omitempty"` 186 187 // Assignee filters issues based on their assignee. Possible values are a 188 // user name, "none" for issues that are not assigned, "*" for issues with 189 // any assigned user. 190 Assignee string `url:"assignee,omitempty"` 191 192 // Creator filters issues based on their creator. 193 Creator string `url:"creator,omitempty"` 194 195 // Mentioned filters issues to those mentioned a specific user. 196 Mentioned string `url:"mentioned,omitempty"` 197 198 // Labels filters issues based on their label. 199 Labels []string `url:"labels,omitempty,comma"` 200 201 // Sort specifies how to sort issues. Possible values are: created, updated, 202 // and comments. Default value is "created". 203 Sort string `url:"sort,omitempty"` 204 205 // Direction in which to sort issues. Possible values are: asc, desc. 206 // Default is "desc". 207 Direction string `url:"direction,omitempty"` 208 209 // Since filters issues by time. 210 Since time.Time `url:"since,omitempty"` 211 212 ListOptions 213} 214 215// ListByRepo lists the issues for the specified repository. 216// 217// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#list-repository-issues 218func (s *IssuesService) ListByRepo(ctx context.Context, owner string, repo string, opts *IssueListByRepoOptions) ([]*Issue, *Response, error) { 219 u := fmt.Sprintf("repos/%v/%v/issues", owner, repo) 220 u, err := addOptions(u, opts) 221 if err != nil { 222 return nil, nil, err 223 } 224 225 req, err := s.client.NewRequest("GET", u, nil) 226 if err != nil { 227 return nil, nil, err 228 } 229 230 // TODO: remove custom Accept header when this API fully launches. 231 req.Header.Set("Accept", mediaTypeReactionsPreview) 232 233 var issues []*Issue 234 resp, err := s.client.Do(ctx, req, &issues) 235 if err != nil { 236 return nil, resp, err 237 } 238 239 return issues, resp, nil 240} 241 242// Get a single issue. 243// 244// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#get-an-issue 245func (s *IssuesService) Get(ctx context.Context, owner string, repo string, number int) (*Issue, *Response, error) { 246 u := fmt.Sprintf("repos/%v/%v/issues/%d", owner, repo, number) 247 req, err := s.client.NewRequest("GET", u, nil) 248 if err != nil { 249 return nil, nil, err 250 } 251 252 // TODO: remove custom Accept header when this API fully launch. 253 req.Header.Set("Accept", mediaTypeReactionsPreview) 254 255 issue := new(Issue) 256 resp, err := s.client.Do(ctx, req, issue) 257 if err != nil { 258 return nil, resp, err 259 } 260 261 return issue, resp, nil 262} 263 264// Create a new issue on the specified repository. 265// 266// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#create-an-issue 267func (s *IssuesService) Create(ctx context.Context, owner string, repo string, issue *IssueRequest) (*Issue, *Response, error) { 268 u := fmt.Sprintf("repos/%v/%v/issues", owner, repo) 269 req, err := s.client.NewRequest("POST", u, issue) 270 if err != nil { 271 return nil, nil, err 272 } 273 274 i := new(Issue) 275 resp, err := s.client.Do(ctx, req, i) 276 if err != nil { 277 return nil, resp, err 278 } 279 280 return i, resp, nil 281} 282 283// Edit an issue. 284// 285// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#update-an-issue 286func (s *IssuesService) Edit(ctx context.Context, owner string, repo string, number int, issue *IssueRequest) (*Issue, *Response, error) { 287 u := fmt.Sprintf("repos/%v/%v/issues/%d", owner, repo, number) 288 req, err := s.client.NewRequest("PATCH", u, issue) 289 if err != nil { 290 return nil, nil, err 291 } 292 293 i := new(Issue) 294 resp, err := s.client.Do(ctx, req, i) 295 if err != nil { 296 return nil, resp, err 297 } 298 299 return i, resp, nil 300} 301 302// LockIssueOptions specifies the optional parameters to the 303// IssuesService.Lock method. 304type LockIssueOptions struct { 305 // LockReason specifies the reason to lock this issue. 306 // Providing a lock reason can help make it clearer to contributors why an issue 307 // was locked. Possible values are: "off-topic", "too heated", "resolved", and "spam". 308 LockReason string `json:"lock_reason,omitempty"` 309} 310 311// Lock an issue's conversation. 312// 313// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#lock-an-issue 314func (s *IssuesService) Lock(ctx context.Context, owner string, repo string, number int, opts *LockIssueOptions) (*Response, error) { 315 u := fmt.Sprintf("repos/%v/%v/issues/%d/lock", owner, repo, number) 316 req, err := s.client.NewRequest("PUT", u, opts) 317 if err != nil { 318 return nil, err 319 } 320 321 return s.client.Do(ctx, req, nil) 322} 323 324// Unlock an issue's conversation. 325// 326// GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues/#unlock-an-issue 327func (s *IssuesService) Unlock(ctx context.Context, owner string, repo string, number int) (*Response, error) { 328 u := fmt.Sprintf("repos/%v/%v/issues/%d/lock", owner, repo, number) 329 req, err := s.client.NewRequest("DELETE", u, nil) 330 if err != nil { 331 return nil, err 332 } 333 334 return s.client.Do(ctx, req, nil) 335} 336