Module: Octokit::Client::Issues

Included in:
Octokit::Client
Defined in:
lib/octokit/client/issues.rb

Overview

Methods for the Issues API

See Also:

Instance Method Summary collapse

Instance Method Details

#add_assignees(repo, number, assignees, options = {}) ⇒ Sawyer::Resource

Add assignees to an issue

Examples:

Add assignees "pengwynn" and "joeyw" to Issue #23 on octokit/octokit.rb

Octokit.add_assignees("octokit/octokit.rb", 23, ["pengwynn", "joeyw"])

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Issue number

  • assignees (Array<String>) —

    Assignees to be added

Returns:

  • (Sawyer::Resource) —

    Issue

See Also:



344
345
346
 
# File 'lib/octokit/client/issues.rb', line 344

def add_assignees(repo, number, assignees, options = {})
  post "#{Repository.path repo}/issues/#{number}/assignees", options.merge({ assignees: assignees })
end

#add_comment(repo, number, comment, options = {}) ⇒ Sawyer::Resource

Add a comment to an issue

Examples:

Add the comment "Almost to v1" to Issue #23 on octokit/octokit.rb

Octokit.add_comment("octokit/octokit.rb", 23, "Almost to v1")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Issue number

  • comment (String) —

    Comment to be added

Returns:

  • (Sawyer::Resource) —

    Comment

See Also:



283
284
285
 
# File 'lib/octokit/client/issues.rb', line 283

def add_comment(repo, number, comment, options = {})
  post "#{Repository.path repo}/issues/#{number}/comments", options.merge({ body: comment })
end

#close_issue(repo, number, options = {}) ⇒ Sawyer::Resource

Close an issue

Examples:

Close Issue #25 from octokit/octokit.rb

Octokit.close_issue("octokit/octokit.rb", "25")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Number ID of the issue

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :assignee (String) —

    User login.

  • :assignees (Array<String>) —

    User login.

  • :milestone (Integer) —

    Milestone number.

  • :labels (Array<String>) —

    List of Label names. Example: ['bug', 'ui', '@high'].

Returns:

  • (Sawyer::Resource) —

    The updated Issue

See Also:



131
132
133
 
# File 'lib/octokit/client/issues.rb', line 131

def close_issue(repo, number, options = {})
  patch "#{Repository.path repo}/issues/#{number}", options.merge({ state: 'closed' })
end

#create_issue(repo, title, body = nil, options = {}) ⇒ Sawyer::Resource Also known as: open_issue

Create an issue for a repository

Examples:

Create a new Issues for a repository

Octokit.create_issue("sferik/rails_admin", 'Updated Docs', 'Added some extra links')

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • title (String) —

    A descriptive title

  • body (String) (defaults to: nil) —

    An optional concise description

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :assignee (String) —

    User login.

  • :assignees (Array<String>) —

    User login.

  • :milestone (Integer) —

    Milestone number.

  • :labels (String) —

    List of comma separated Label names. Example: bug,ui,@high.

Returns:

  • (Sawyer::Resource) —

    Your newly created issue

See Also:



91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/octokit/client/issues.rb', line 91

def create_issue(repo, title, body = nil, options = {})
  options[:labels] = case options[:labels]
                     when String
                       options[:labels].split(',').map(&:strip)
                     when Array
                       options[:labels]
                     else
                       []
                     end
  parameters = { title: title }
  parameters[:body] = body unless body.nil?
  post "#{Repository.path repo}/issues", options.merge(parameters)
end

#delete_comment(repo, number, options = {}) ⇒ Boolean

Delete a single comment

Examples:

Delete the comment #1194549 on an issue on octokit/octokit.rb

Octokit.delete_comment("octokit/octokit.rb", 1194549)

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Comment number

Returns:

  • (Boolean) —

    Success

See Also:



308
309
310
 
# File 'lib/octokit/client/issues.rb', line 308

def delete_comment(repo, number, options = {})
  boolean_from_response :delete, "#{Repository.path repo}/issues/comments/#{number}", options
end

#issue(repo, number, options = {}) ⇒ Sawyer::Resource

Get a single issue from a repository

Examples:

Get issue #25 from octokit/octokit.rb

Octokit.issue("octokit/octokit.rb", "25")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Number ID of the issue

Returns:

  • (Sawyer::Resource) —

    The issue you requested, if it exists

See Also:



114
115
116
 
# File 'lib/octokit/client/issues.rb', line 114

def issue(repo, number, options = {})
  get "#{Repository.path repo}/issues/#{number}", options
end

#issue_comment(repo, number, options = {}) ⇒ Sawyer::Resource

Get a single comment attached to an issue

Examples:

Get comment #1194549 from an issue on octokit/octokit.rb

Octokit.issue_comment("octokit/octokit.rb", 1194549)

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Number ID of the comment

Returns:

  • (Sawyer::Resource) —

    The specific comment in question

See Also:



270
271
272
 
# File 'lib/octokit/client/issues.rb', line 270

def issue_comment(repo, number, options = {})
  paginate "#{Repository.path repo}/issues/comments/#{number}", options
end

#issue_comments(repo, number, options = {}) ⇒ Array<Sawyer::Resource>

Get all comments attached to an issue

Examples:

Get comments for issue #25 from octokit/octokit.rb

Octokit.issue_comments("octokit/octokit.rb", "25")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Number ID of the issue

Returns:

  • (Array<Sawyer::Resource>) —

    Array of comments that belong to an issue

See Also:



258
259
260
 
# File 'lib/octokit/client/issues.rb', line 258

def issue_comments(repo, number, options = {})
  paginate "#{Repository.path repo}/issues/#{number}/comments", options
end

#issue_timeline(repo, number, options = {}) ⇒ Sawyer::Resource

Get the timeline for an issue

Examples:

Get timeline for issue #1435 on octokit/octokit.rb

Octokit.issue_timeline("octokit/octokit.rb", 1435)

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Number ID of the comment

Returns:

  • (Sawyer::Resource) —

    The timeline for this issue

See Also:



320
321
322
 
# File 'lib/octokit/client/issues.rb', line 320

def issue_timeline(repo, number, options = {})
  paginate "#{Repository.path repo}/issues/#{number}/timeline", options
end

#issues_comments(repo, options = {}) ⇒ Array<Sawyer::Resource>

Get all comments attached to issues for the repository

By default, Issue Comments are ordered by ascending ID.

Examples:

Get the comments for issues in the octokit repository

@client.issues_comments("octokit/octokit.rb")

Get issues comments, sort by updated descending since a time

@client.issues_comments("octokit/octokit.rb", {
  :sort => 'desc',
  :direction => 'asc',
  :since => '2010-05-04T23:45:02Z'
})

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • options (Hash) (defaults to: {}) —

    Optional parameters

Options Hash (options):

  • :sort (String) —

    created or updated

  • :direction (String) —

    asc or desc. Ignored without sort parameter.

  • :since (String) —

    Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Returns:

  • (Array<Sawyer::Resource>) —

    List of issues comments.

See Also:



246
247
248
 
# File 'lib/octokit/client/issues.rb', line 246

def issues_comments(repo, options = {})
  paginate "#{Repository.path repo}/issues/comments", options
end

#list_assignees(repo, options = {}) ⇒ Array<Sawyer::Resource>

Lists the available assignees for issues in a repository.

Examples:

Get available assignees on repository octokit/octokit.rb

Octokit.list_assignees("octokit/octokit.rb")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

Returns:

  • (Array<Sawyer::Resource>) —

    List of GitHub users.

See Also:



331
332
333
 
# File 'lib/octokit/client/issues.rb', line 331

def list_assignees(repo, options = {})
  paginate "#{Repository.path repo}/assignees", options
end

#list_issues(repository = nil, options = {}) ⇒ Array<Sawyer::Resource> Also known as: issues

List issues for the authenticated user or repository

Examples:

List issues for a repository

Octokit.list_issues("sferik/rails_admin")

List issues for the authenticated user across repositories

@client = Octokit::Client.new(:login => 'foo', :password => 'bar')
@client.list_issues

Parameters:

  • repository (Integer, String, Repository, Hash) (defaults to: nil) —

    A GitHub repository.

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :milestone (Integer) —

    Milestone number.

  • :state (String) — default: open —

    State: open, closed, or all.

  • :assignee (String) —

    User login.

  • :creator (String) —

    User login.

  • :mentioned (String) —

    User login.

  • :labels (String) —

    List of comma separated Label names. Example: bug,ui,@high.

  • :sort (String) — default: created —

    Sort: created, updated, or comments.

  • :direction (String) — default: desc —

    Direction: asc or desc.

  • :page (Integer) — default: 1 —

    Page number.

Returns:

  • (Array<Sawyer::Resource>) —

    A list of issues for a repository.

See Also:



30
31
32
33
 
# File 'lib/octokit/client/issues.rb', line 30

def list_issues(repository = nil, options = {})
  path = repository ? "#{Repository.new(repository).path}/issues" : 'issues'
  paginate path, options
end

#lock_issue(repo, number, options = {}) ⇒ Boolean

Lock an issue's conversation, limiting it to collaborators

Examples:

Lock Issue #25 from octokit/octokit.rb

Octokit.lock_issue("octokit/octokit.rb", "25")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Number ID of the issue

Returns:

  • (Boolean) —

    Success

See Also:



160
161
162
 
# File 'lib/octokit/client/issues.rb', line 160

def lock_issue(repo, number, options = {})
  boolean_from_response :put, "#{Repository.path repo}/issues/#{number}/lock", options
end

#org_issues(org, options = {}) ⇒ Array<Sawyer::Resource>

List all issues for a given organization for the authenticated user

Examples:

List all issues for a given organization for the authenticated user

@client = Octokit::Client.new(:login => 'foo', :password => 'bar')
@client.org_issues("octokit")

Parameters:

  • org (String, Integer) —

    Organization GitHub login or id.

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :filter (String) — default: assigned —

    State: assigned, created, mentioned, subscribed or closed.

  • :state (String) — default: open —

    State: open, closed, or all.

  • :labels (Array<String>) —

    List of Label names. Example: ['bug', 'ui', '@high'].

  • :sort (String) — default: created —

    Sort: created, updated, or comments.

  • :direction (String) — default: desc —

    Direction: asc or desc.

  • :page (Integer) — default: 1 —

    Page number.

  • :since (String) —

    Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Returns:

  • (Array<Sawyer::Resource>) —

    A list of issues.

See Also:



73
74
75
 
# File 'lib/octokit/client/issues.rb', line 73

def org_issues(org, options = {})
  paginate "#{Organization.path org}/issues", options
end

#remove_assignees(repo, number, assignees, options = {}) ⇒ Sawyer::Resource

Remove assignees from an issue

Examples:

Remove assignees "pengwynn" and "joeyw" from Issue #23 on octokit/octokit.rb

Octokit.remove_assignees("octokit/octokit.rb", 23, ["pengwynn", "joeyw"])

Remove assignees "pengwynn" from Issue #23 on octokit/octokit.rb

Octokit.remove_assignees("octokit/octokit.rb", 23, ["pengwynn"],
  :accept => "application/vnd.github.v3+json")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Issue number

  • assignees (Array<String>) —

    Assignees to be removed

  • options (Hash) (defaults to: {}) —

    Header params for request

Returns:

  • (Sawyer::Resource) —

    Issue

See Also:



362
363
364
 
# File 'lib/octokit/client/issues.rb', line 362

def remove_assignees(repo, number, assignees, options = {})
  delete "#{Repository.path repo}/issues/#{number}/assignees", options.merge({ assignees: assignees })
end

#reopen_issue(repo, number, options = {}) ⇒ Sawyer::Resource

Reopen an issue

Examples:

Reopen Issue #25 from octokit/octokit.rb

Octokit.reopen_issue("octokit/octokit.rb", "25")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Number ID of the issue

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :assignee (String) —

    User login.

  • :assignees (Array<String>) —

    User login.

  • :milestone (Integer) —

    Milestone number.

  • :labels (Array<String>) —

    List of Label names. Example: ['bug', 'ui', '@high'].

Returns:

  • (Sawyer::Resource) —

    The updated Issue

See Also:



148
149
150
 
# File 'lib/octokit/client/issues.rb', line 148

def reopen_issue(repo, number, options = {})
  patch "#{Repository.path repo}/issues/#{number}", options.merge({ state: 'open' })
end

#unlock_issue(repo, number, options = {}) ⇒ Boolean

Unlock an issue's conversation, opening it to all viewers

Examples:

Unlock Issue #25 from octokit/octokit.rb

Octokit.close_issue("octokit/octokit.rb", "25")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Number ID of the issue

Returns:

  • (Boolean) —

    Success

See Also:



172
173
174
 
# File 'lib/octokit/client/issues.rb', line 172

def unlock_issue(repo, number, options = {})
  boolean_from_response :delete, "#{Repository.path repo}/issues/#{number}/lock", options
end

#update_comment(repo, number, comment, options = {}) ⇒ Sawyer::Resource

Update a single comment on an issue

Examples:

Update the comment #1194549 with body "I've started this on my 25-issue-comments-v3 fork" on an issue on octokit/octokit.rb

Octokit.update_comment("octokit/octokit.rb", 1194549, "Almost to v1, added this on my fork")

Parameters:

  • repo (Integer, String, Repository, Hash) —

    A GitHub repository

  • number (Integer) —

    Comment number

  • comment (String) —

    Body of the comment which will replace the existing body.

Returns:

  • (Sawyer::Resource) —

    Comment

See Also:



296
297
298
 
# File 'lib/octokit/client/issues.rb', line 296

def update_comment(repo, number, comment, options = {})
  patch "#{Repository.path repo}/issues/comments/#{number}", options.merge({ body: comment })
end

#update_issue(repo, number, title, body, options) ⇒ Sawyer::Resource #update_issue(repo, number, options) ⇒ Sawyer::Resource

Update an issue

Examples:

Change the title of Issue #25

Octokit.update_issue("octokit/octokit.rb", "25", "A new title", "the same body")

Change only the assignee of Issue #25

Octokit.update_issue("octokit/octokit.rb", "25", :assignee => "pengwynn")

Overloads:

  • #update_issue(repo, number, title, body, options) ⇒ Sawyer::Resource

    Parameters:

    • repo (Integer, String, Repository, Hash) —

      A GitHub repository

    • number (Integer) —

      Number ID of the issue

    • title (String) —

      Updated title for the issue

    • body (String) —

      Updated body of the issue

    • options (Hash) —

      A customizable set of options.

    Options Hash (options):

    • :assignee (String) —

      User login.

    • :assignees (Array<String>) —

      User login.

    • :milestone (Integer) —

      Milestone number.

    • :labels (String) —

      List of comma separated Label names. Example: bug,ui,@high.

    • :state (String) —

      State of the issue. open or closed

  • #update_issue(repo, number, options) ⇒ Sawyer::Resource

    Parameters:

    • repo (Integer, String, Repository, Hash) —

      A GitHub repository

    • number (Integer) —

      Number ID of the issue

    • options (Hash) —

      A customizable set of options.

    Options Hash (options):

    • :title (String) —

      Updated title for the issue

    • :body (String) —

      Updated body of the issue

    • :assignee (String) —

      User login.

    • :assignees (Array<String>) —

      User login.

    • :milestone (Integer) —

      Milestone number.

Parameters:

  • options (Hash) —

    a customizable set of options

Returns:

  • (Sawyer::Resource) —

    The updated Issue

See Also:



209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/octokit/client/issues.rb', line 209

def update_issue(repo, number, *args)
  arguments = Arguments.new(args)
  opts = arguments.options

  unless arguments.empty?
    opts[:title] = arguments.shift
    opts[:body] = arguments.shift
  end

  patch "#{Repository.path repo}/issues/#{number}", opts
end

#user_issues(options = {}) ⇒ Array<Sawyer::Resource>

List all issues across owned and member repositories for the authenticated user

Examples:

List issues for the authenticated user across owned and member repositories

@client = Octokit::Client.new(:login => 'foo', :password => 'bar')
@client.user_issues

Parameters:

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :filter (String) — default: assigned —

    State: assigned, created, mentioned, subscribed or closed.

  • :state (String) — default: open —

    State: open, closed, or all.

  • :labels (Array<String>) —

    List of Label names. Example: ['bug', 'ui', '@high'].

  • :sort (String) — default: created —

    Sort: created, updated, or comments.

  • :direction (String) — default: desc —

    Direction: asc or desc.

  • :page (Integer) — default: 1 —

    Page number.

  • :since (String) —

    Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Returns:

  • (Array<Sawyer::Resource>) —

    A list of issues for a repository.

See Also:



52
53
54
 
# File 'lib/octokit/client/issues.rb', line 52

def user_issues(options = {})
  paginate 'user/issues', options
end