0
# Issue Management
1
2
Complete issue lifecycle management including creation, editing, commenting, labeling, milestones, assignees, and issue events tracking.
3
4
## Capabilities
5
6
### Issue Access & Listing
7
8
Core operations for accessing and listing issues across repositories and users.
9
10
```python { .api }
11
class GitHub:
12
def issue(self, owner, repository, number):
13
"""
14
Get a specific issue by number.
15
16
Args:
17
owner (str): Repository owner
18
repository (str): Repository name
19
number (int): Issue number
20
21
Returns:
22
Issue: Issue object or None if not found
23
"""
24
25
def issues(self, filter="assigned", state="open", labels="", sort="created",
26
direction="desc", since=None):
27
"""
28
List issues for the authenticated user.
29
30
Args:
31
filter (str): Filter type ('assigned', 'created', 'mentioned', 'subscribed', 'all')
32
state (str): Issue state ('open', 'closed', 'all')
33
labels (str): Comma-separated list of label names
34
sort (str): Sort by ('created', 'updated', 'comments')
35
direction (str): Sort direction ('asc', 'desc')
36
since (str, optional): ISO 8601 timestamp
37
38
Returns:
39
iterator: Iterator of Issue objects
40
"""
41
42
def issues_on(self, owner, repository, milestone=None, state="open",
43
assignee=None, creator=None, mentioned=None, labels=None,
44
sort="created", direction="desc", since=None):
45
"""
46
List issues for a repository.
47
48
Args:
49
owner (str): Repository owner
50
repository (str): Repository name
51
milestone (str or int, optional): Milestone number or '*' for any, 'none' for no milestone
52
state (str): Issue state ('open', 'closed', 'all')
53
assignee (str, optional): Username or '*' for any, 'none' for unassigned
54
creator (str, optional): Username of issue creator
55
mentioned (str, optional): Username mentioned in issue
56
labels (str, optional): Comma-separated label names
57
sort (str): Sort by ('created', 'updated', 'comments')
58
direction (str): Sort direction ('asc', 'desc')
59
since (str, optional): ISO 8601 timestamp
60
61
Returns:
62
iterator: Iterator of Issue objects
63
"""
64
```
65
66
**Usage Examples:**
67
68
```python
69
import github3
70
71
gh = github3.login(token='your_token')
72
73
# Get a specific issue
74
issue = gh.issue('octocat', 'Hello-World', 1)
75
print(f"Issue: {issue.title}")
76
print(f"State: {issue.state}")
77
print(f"Comments: {issue.comments}")
78
79
# List user's assigned issues
80
for issue in gh.issues(filter='assigned', state='open'):
81
print(f"#{issue.number}: {issue.title}")
82
83
# List repository issues
84
for issue in gh.issues_on('octocat', 'Hello-World', state='all'):
85
print(f"#{issue.number}: {issue.title} ({issue.state})")
86
```
87
88
### Issue Creation & Management
89
90
Operations for creating, updating, and managing issues.
91
92
```python { .api }
93
class GitHub:
94
def create_issue(self, owner, repository, title, body=None, assignee=None,
95
milestone=None, labels=[], assignees=None):
96
"""
97
Create an issue on a repository.
98
99
Args:
100
owner (str): Repository owner
101
repository (str): Repository name
102
title (str): Issue title
103
body (str, optional): Issue description
104
assignee (str, optional): Username to assign to
105
milestone (int, optional): Milestone number
106
labels (list): List of label names
107
assignees (list, optional): List of usernames to assign to
108
109
Returns:
110
Issue: Created issue object
111
"""
112
113
class Repository:
114
def create_issue(self, title, body="", assignee="", milestone=None, labels=[]):
115
"""
116
Create an issue in this repository.
117
118
Args:
119
title (str): Issue title
120
body (str): Issue description
121
assignee (str, optional): Username to assign to
122
milestone (int, optional): Milestone number
123
labels (list): List of label names
124
125
Returns:
126
Issue: Created issue object
127
"""
128
129
class Issue:
130
def edit(self, title=None, body=None, assignee=None, state=None,
131
milestone=None, labels=None):
132
"""
133
Edit this issue.
134
135
Args:
136
title (str, optional): New title
137
body (str, optional): New description
138
assignee (str, optional): New assignee
139
state (str, optional): New state ('open', 'closed')
140
milestone (int, optional): Milestone number
141
labels (list, optional): List of label names
142
143
Returns:
144
bool: True if successful
145
"""
146
147
def close(self):
148
"""
149
Close this issue.
150
151
Returns:
152
bool: True if successful
153
"""
154
155
def reopen(self):
156
"""
157
Reopen this issue.
158
159
Returns:
160
bool: True if successful
161
"""
162
```
163
164
**Usage Examples:**
165
166
```python
167
# Create a new issue directly on GitHub client
168
issue = gh.create_issue(
169
'octocat', 'Hello-World',
170
title='Bug in hello function',
171
body='The hello function returns the wrong greeting.',
172
assignee='octocat',
173
labels=['bug', 'priority-high']
174
)
175
print(f"Created issue #{issue.number}")
176
177
# Or create via repository object (more efficient for multiple operations)
178
repo = gh.repository('octocat', 'Hello-World')
179
issue = repo.create_issue(
180
title='Another bug report',
181
body='Found another issue.',
182
assignee='octocat',
183
labels=['bug', 'priority-high']
184
)
185
print(f"Created issue #{issue.number}")
186
187
# Edit the issue
188
issue.edit(
189
title='Updated: Bug in hello function',
190
body='Updated description with more details.',
191
labels=['bug', 'priority-medium', 'needs-review']
192
)
193
194
# Close the issue
195
issue.close()
196
```
197
198
### Issue Comments
199
200
Managing comments on issues.
201
202
```python { .api }
203
class Issue:
204
def comments(self, sort="created", direction="asc", since=None):
205
"""
206
List comments on this issue.
207
208
Args:
209
sort (str): Sort by ('created', 'updated')
210
direction (str): Sort direction ('asc', 'desc')
211
since (str, optional): ISO 8601 timestamp
212
213
Returns:
214
iterator: Iterator of IssueComment objects
215
"""
216
217
def create_comment(self, body):
218
"""
219
Create a comment on this issue.
220
221
Args:
222
body (str): Comment text
223
224
Returns:
225
IssueComment: Created comment object
226
"""
227
228
class IssueComment:
229
def edit(self, body):
230
"""
231
Edit this comment.
232
233
Args:
234
body (str): New comment text
235
236
Returns:
237
bool: True if successful
238
"""
239
240
def delete(self):
241
"""
242
Delete this comment.
243
244
Returns:
245
bool: True if successful
246
"""
247
```
248
249
**Usage Examples:**
250
251
```python
252
# Add a comment to an issue
253
comment = issue.create_comment("This is a great point, I'll look into it.")
254
255
# List comments
256
for comment in issue.comments():
257
print(f"Comment by {comment.user.login}: {comment.body[:100]}...")
258
259
# Edit and delete comments
260
comment.edit("Updated comment text.")
261
comment.delete()
262
```
263
264
### Labels Management
265
266
Managing issue labels.
267
268
```python { .api }
269
class Repository:
270
def labels(self):
271
"""
272
List repository labels.
273
274
Returns:
275
iterator: Iterator of Label objects
276
"""
277
278
def label(self, name):
279
"""
280
Get a specific label.
281
282
Args:
283
name (str): Label name
284
285
Returns:
286
Label: Label object or None
287
"""
288
289
def create_label(self, name, color, description=""):
290
"""
291
Create a new label.
292
293
Args:
294
name (str): Label name
295
color (str): Label color (hex code without #)
296
description (str): Label description
297
298
Returns:
299
Label: Created label object
300
"""
301
302
class Issue:
303
def add_labels(self, *labels):
304
"""
305
Add labels to this issue.
306
307
Args:
308
*labels: Label names or Label objects
309
310
Returns:
311
list: List of Label objects
312
"""
313
314
def remove_label(self, label):
315
"""
316
Remove a label from this issue.
317
318
Args:
319
label (str or Label): Label name or object
320
321
Returns:
322
bool: True if successful
323
"""
324
325
def remove_all_labels(self):
326
"""
327
Remove all labels from this issue.
328
329
Returns:
330
bool: True if successful
331
"""
332
333
def replace_labels(self, labels):
334
"""
335
Replace all labels on this issue.
336
337
Args:
338
labels (list): List of label names
339
340
Returns:
341
list: List of Label objects
342
"""
343
```
344
345
### Milestones Management
346
347
Managing issue milestones.
348
349
```python { .api }
350
class Repository:
351
def milestones(self, state="open", sort="due_on", direction="asc"):
352
"""
353
List repository milestones.
354
355
Args:
356
state (str): Milestone state ('open', 'closed', 'all')
357
sort (str): Sort by ('due_on', 'completeness')
358
direction (str): Sort direction ('asc', 'desc')
359
360
Returns:
361
iterator: Iterator of Milestone objects
362
"""
363
364
def milestone(self, number):
365
"""
366
Get a specific milestone.
367
368
Args:
369
number (int): Milestone number
370
371
Returns:
372
Milestone: Milestone object or None
373
"""
374
375
def create_milestone(self, title, state="open", description="", due_on=None):
376
"""
377
Create a new milestone.
378
379
Args:
380
title (str): Milestone title
381
state (str): Milestone state ('open', 'closed')
382
description (str): Milestone description
383
due_on (str, optional): Due date (ISO 8601 format)
384
385
Returns:
386
Milestone: Created milestone object
387
"""
388
389
class Milestone:
390
def edit(self, title=None, state=None, description=None, due_on=None):
391
"""
392
Edit this milestone.
393
394
Args:
395
title (str, optional): New title
396
state (str, optional): New state
397
description (str, optional): New description
398
due_on (str, optional): New due date
399
400
Returns:
401
bool: True if successful
402
"""
403
404
def delete(self):
405
"""
406
Delete this milestone.
407
408
Returns:
409
bool: True if successful
410
"""
411
```
412
413
### Issue Events & Timeline
414
415
Tracking issue events and timeline.
416
417
```python { .api }
418
class Issue:
419
def events(self):
420
"""
421
List events for this issue.
422
423
Returns:
424
iterator: Iterator of IssueEvent objects
425
"""
426
427
def timeline(self):
428
"""
429
Get the complete timeline for this issue.
430
431
Returns:
432
iterator: Iterator of timeline events
433
"""
434
```
435
436
### Issue Assignment
437
438
Managing issue assignees.
439
440
```python { .api }
441
class Issue:
442
def assign(self, assignee):
443
"""
444
Assign this issue to a user.
445
446
Args:
447
assignee (str): Username to assign to
448
449
Returns:
450
bool: True if successful
451
"""
452
453
def remove_assignee(self, assignee):
454
"""
455
Remove an assignee from this issue.
456
457
Args:
458
assignee (str): Username to remove
459
460
Returns:
461
bool: True if successful
462
"""
463
464
def add_assignees(self, assignees):
465
"""
466
Add multiple assignees to this issue.
467
468
Args:
469
assignees (list): List of usernames
470
471
Returns:
472
Issue: Updated issue object
473
"""
474
475
def remove_assignees(self, assignees):
476
"""
477
Remove multiple assignees from this issue.
478
479
Args:
480
assignees (list): List of usernames
481
482
Returns:
483
Issue: Updated issue object
484
"""
485
```
486
487
## Issue Model Classes
488
489
```python { .api }
490
class Issue:
491
"""Full issue object with all data and methods."""
492
id: int
493
number: int
494
title: str
495
body: str
496
user: 'User'
497
labels: list # List of Label objects
498
state: str # 'open' or 'closed'
499
locked: bool
500
assignee: 'User'
501
assignees: list # List of User objects
502
milestone: 'Milestone'
503
comments: int
504
created_at: str
505
updated_at: str
506
closed_at: str
507
closed_by: 'User'
508
pull_request: dict # If issue is a PR
509
repository: 'Repository'
510
html_url: str
511
512
def edit(self, **kwargs): ...
513
def close(self): ...
514
def reopen(self): ...
515
def create_comment(self, body): ...
516
def add_labels(self, *labels): ...
517
def assign(self, assignee): ...
518
519
class ShortIssue:
520
"""Abbreviated issue object for listings."""
521
id: int
522
number: int
523
title: str
524
state: str
525
user: 'ShortUser'
526
527
class IssueComment:
528
"""Comment on an issue."""
529
id: int
530
body: str
531
user: 'User'
532
created_at: str
533
updated_at: str
534
html_url: str
535
issue_url: str
536
537
def edit(self, body): ...
538
def delete(self): ...
539
540
class Label:
541
"""Issue label."""
542
id: int
543
name: str
544
color: str
545
description: str
546
default: bool
547
url: str
548
549
def edit(self, name=None, color=None, description=None): ...
550
def delete(self): ...
551
552
class ShortLabel:
553
"""Abbreviated label object."""
554
name: str
555
color: str
556
557
class Milestone:
558
"""Issue milestone."""
559
id: int
560
number: int
561
title: str
562
description: str
563
state: str # 'open' or 'closed'
564
creator: 'User'
565
open_issues: int
566
closed_issues: int
567
created_at: str
568
updated_at: str
569
closed_at: str
570
due_on: str
571
html_url: str
572
573
def edit(self, **kwargs): ...
574
def delete(self): ...
575
576
class IssueEvent:
577
"""Issue timeline event."""
578
id: int
579
event: str # 'closed', 'reopened', 'labeled', etc.
580
actor: 'User'
581
created_at: str
582
commit_id: str
583
commit_url: str
584
label: 'Label'
585
assignee: 'User'
586
assigner: 'User'
587
milestone: 'Milestone'
588
```