0
# Issues & Pull Request Management
1

2
Complete issue and pull request lifecycle management including creation, modification, labeling, milestones, and collaboration features for GitHub's project tracking and code review workflows.
3

4
## Capabilities
5

6
### Issue Retrieval
7

8
Access issues across repositories with flexible filtering and pagination options.
9

10
```python { .api }
11
def issue(self, username, repository, number):
12
    """
13
    Fetch a specific issue from a repository.
14
    
15
    Parameters:
16
    - username (str, required): Repository owner
17
    - repository (str, required): Repository name
18
    - number (int, required): Issue number
19
    
20
    Returns:
21
    Issue object with full details or None if not found
22
    """
23

24
def issues(self, filter="", state="", labels="", sort="", direction="", since=None, number=-1, etag=None):
25
    """
26
    List all issues for the authenticated user across organizations.
27
    
28
    Parameters:
29
    - filter (str, optional): 'assigned', 'created', 'mentioned', 'subscribed'
30
    - state (str, optional): 'all', 'open', 'closed'
31
    - labels (str, optional): Comma-separated label names
32
    - sort (str, optional): 'created', 'updated', 'comments'
33
    - direction (str, optional): 'asc', 'desc'
34
    - since (datetime/str, optional): Only issues after this date
35
    - number (int): Number to return (-1 for all)
36
    - etag (str, optional): ETag from previous request
37
    
38
    Returns:
39
    Generator of ShortIssue objects
40
    """
41

42
def issues_on(self, username, repository, milestone=None, state=None, assignee=None, mentioned=None, labels=None, sort=None, direction=None, since=None, number=-1, etag=None):
43
    """
44
    List issues on a specific repository.
45
    
46
    Parameters:
47
    - username (str, required): Repository owner
48
    - repository (str, required): Repository name
49
    - milestone (int/str, optional): Milestone ID, '*' for any, None for no milestone
50
    - state (str, optional): 'all', 'open', 'closed'
51
    - assignee (str, optional): Username or '*' for any assignee
52
    - mentioned (str, optional): Username mentioned in issue
53
    - labels (str, optional): Comma-separated label names
54
    - sort (str, optional): 'created', 'updated', 'comments'
55
    - direction (str, optional): 'asc', 'desc'
56
    - since (datetime/str, optional): Only issues after this date
57
    - number (int): Number to return (-1 for all)
58
    - etag (str, optional): ETag from previous request
59
    
60
    Returns:
61
    Generator of ShortIssue objects
62
    """
63

64
def user_issues(self, filter="", state="", labels="", sort="", direction="", since=None, per_page=None, number=-1, etag=None):
65
    """
66
    List only the authenticated user's own issues (not organization issues).
67
    
68
    Parameters:
69
    - filter (str, optional): 'assigned', 'created', 'mentioned', 'subscribed'
70
    - state (str, optional): 'all', 'open', 'closed'
71
    - labels (str, optional): Comma-separated label names
72
    - sort (str, optional): 'created', 'updated', 'comments'
73
    - direction (str, optional): 'asc', 'desc'
74
    - since (datetime/str, optional): Only issues after this date
75
    - per_page (int, optional): Results per page
76
    - number (int): Number to return (-1 for all)
77
    - etag (str, optional): ETag from previous request
78
    
79
    Returns:
80
    Generator of ShortIssue objects
81
    """
82
```
83

84
### Usage Examples
85

86
```python
87
# Get specific issue
88
issue = gh.issue('octocat', 'Hello-World', 1)
89
print(f"Issue #{issue.number}: {issue.title}")
90
print(f"State: {issue.state}")
91
print(f"Author: {issue.user.login}")
92

93
# List all your issues
94
for issue in gh.issues(filter='assigned', state='open'):
95
    print(f"{issue.repository.full_name}#{issue.number}: {issue.title}")
96

97
# List repository issues with filters
98
for issue in gh.issues_on('owner', 'repo', state='open', labels='bug,priority-high'):
99
    print(f"Bug #{issue.number}: {issue.title}")
100

101
# List your own issues only
102
for issue in gh.user_issues(filter='created', sort='updated'):
103
    print(f"Created issue: {issue.title}")
104
```
105

106
### Issue Creation
107

108
Create new issues with comprehensive options for project tracking and bug reporting.
109

110
```python { .api }
111
def create_issue(self, owner, repository, title, body=None, assignee=None, milestone=None, labels=[], assignees=None):
112
    """
113
    Create an issue on a repository.
114
    
115
    Parameters:
116
    - owner (str, required): Repository owner
117
    - repository (str, required): Repository name
118
    - title (str, required): Issue title
119
    - body (str, optional): Issue description in Markdown
120
    - assignee (str, optional): Username to assign (legacy, use assignees)
121
    - milestone (int, optional): Milestone ID number
122
    - labels (list, optional): List of label names
123
    - assignees (list, optional): List of usernames to assign
124
    
125
    Returns:
126
    ShortIssue object for the created issue
127
    """
128
```
129

130
### Usage Examples
131

132
```python
133
# Create simple issue
134
issue = gh.create_issue('owner', 'repo', 'Bug in login function')
135

136
# Create detailed issue
137
issue = gh.create_issue(
138
    owner='owner',
139
    repository='repo',
140
    title='Add user authentication',
141
    body='''## Description
142
We need to implement user authentication with the following features:
143

144
- [ ] Login form
145
- [ ] Password validation
146
- [ ] Session management
147

148
## Acceptance Criteria
149
- Users can log in with email/password
150
- Sessions expire after 24 hours
151
- Invalid credentials show error message
152
''',
153
    assignees=['developer1', 'developer2'],
154
    labels=['enhancement', 'priority-medium'],
155
    milestone=5
156
)
157

158
print(f"Created issue #{issue.number}: {issue.html_url}")
159
```
160

161
### Pull Request Management
162

163
Access and manage pull requests for code review and collaboration workflows.
164

165
```python { .api }
166
def pull_request(self, owner, repository, number):
167
    """
168
    Fetch a specific pull request from a repository.
169
    
170
    Parameters:
171
    - owner (str, required): Repository owner
172
    - repository (str, required): Repository name
173
    - number (int, required): Pull request number
174
    
175
    Returns:
176
    PullRequest object with full details or None if not found
177
    """
178
```
179

180
### Usage Examples
181

182
```python
183
# Get specific pull request
184
pr = gh.pull_request('owner', 'repo', 42)
185
print(f"PR #{pr.number}: {pr.title}")
186
print(f"State: {pr.state}")
187
print(f"Author: {pr.user.login}")
188
print(f"Base: {pr.base.ref} <- Head: {pr.head.ref}")
189
print(f"Mergeable: {pr.mergeable}")
190

191
# Check PR review status
192
if pr.merged:
193
    print(f"Merged at: {pr.merged_at}")
194
else:
195
    print(f"Comments: {pr.review_comments}")
196
    print(f"Commits: {pr.commits}")
197
```
198

199
### Organization Issue Management
200

201
Manage issues across organization repositories with enhanced filtering and bulk operations.
202

203
```python { .api }
204
def organization_issues(self, name, filter="", state="", labels="", sort="", direction="", since=None, number=-1, etag=None):
205
    """
206
    Iterate over organization issues (requires membership).
207
    
208
    Parameters:
209
    - name (str, required): Organization name
210
    - filter (str, optional): 'assigned', 'created', 'mentioned', 'subscribed'
211
    - state (str, optional): 'all', 'open', 'closed'
212
    - labels (str, optional): Comma-separated label names
213
    - sort (str, optional): 'created', 'updated', 'comments'
214
    - direction (str, optional): 'asc', 'desc'
215
    - since (datetime/str, optional): Only issues after this date
216
    - number (int): Number to return (-1 for all)
217
    - etag (str, optional): ETag from previous request
218
    
219
    Returns:
220
    Generator of ShortIssue objects
221
    """
222
```
223

224
### Usage Examples
225

226
```python 
227
# List organization issues
228
for issue in gh.organization_issues('my-org', filter='assigned', state='open'):
229
    print(f"{issue.repository.name}#{issue.number}: {issue.title}")
230
    print(f"Assigned to: {[a.login for a in issue.assignees]}")
231
```
232

233
## Issue and Pull Request Model Classes
234

235
```python { .api }
236
class Issue:
237
    """Full issue representation with all details and operations"""
238
    id: int
239
    number: int
240
    title: str
241
    body: str
242
    state: str  # 'open' or 'closed'
243
    user: User  # Issue author
244
    assignee: User  # Primary assignee (deprecated)
245
    assignees: list  # List of assigned users
246
    labels: list  # List of Label objects
247
    milestone: Milestone
248
    comments: int
249
    created_at: datetime
250
    updated_at: datetime
251
    closed_at: datetime
252
    repository: Repository
253
    html_url: str
254
    # ... additional issue properties and methods
255

256
class ShortIssue:
257
    """Abbreviated issue representation for list operations"""
258
    id: int
259
    number: int
260
    title: str
261
    state: str
262
    user: User
263
    # ... essential issue properties
264

265
class PullRequest:
266
    """Full pull request representation with code review details"""
267
    id: int
268
    number: int
269
    title: str
270
    body: str
271
    state: str  # 'open', 'closed', 'merged'
272
    user: User
273
    assignee: User
274
    assignees: list
275
    labels: list
276
    milestone: Milestone
277
    head: dict  # Source branch info
278
    base: dict  # Target branch info
279
    merged: bool
280
    mergeable: bool
281
    merged_at: datetime
282
    merged_by: User
283
    commits: int
284
    additions: int
285
    deletions: int
286
    changed_files: int
287
    review_comments: int
288
    # ... additional PR properties and methods
289

290
class ShortPullRequest:
291
    """Abbreviated pull request representation"""
292
    id: int
293
    number: int
294
    title: str
295
    state: str
296
    # ... essential PR properties
297

298
class Label:
299
    """Issue/PR label representation"""
300
    id: int
301
    name: str
302
    color: str
303
    description: str
304
    # ... additional label properties
305

306
class Milestone:
307
    """Issue milestone representation"""
308
    id: int
309
    number: int
310
    title: str
311
    description: str
312
    state: str
313
    created_at: datetime
314
    updated_at: datetime
315
    due_on: datetime
316
    closed_issues: int
317
    open_issues: int
318
    # ... additional milestone properties
319

320
class Comment:
321
    """Issue/PR comment representation"""
322
    id: int
323
    body: str
324
    user: User
325
    created_at: datetime
326
    updated_at: datetime
327
    html_url: str
328
    # ... additional comment properties
329
```
330

331
## Common Issue and PR Patterns
332

333
### Issue Tracking Workflow
334
```python
335
# Create issue from template
336
issue = gh.create_issue(
337
    'owner', 'repo',
338
    title='[BUG] Login fails with special characters',
339
    body='## Bug Report\n**Steps to reproduce:**\n1. ...',
340
    labels=['bug', 'priority-high']
341
)
342

343
# Add comments and updates
344
issue.create_comment('Investigating this issue...')
345
issue.add_labels(['investigating'])
346
```
347

348
### Pull Request Review
349
```python
350
# Get PR and review details
351
pr = gh.pull_request('owner', 'repo', 123)
352

353
# Check review status
354
print(f"Mergeable: {pr.mergeable}")
355
print(f"Review comments: {pr.review_comments}")
356

357
# List PR files and changes
358
for file in pr.files():
359
    print(f"{file.filename}: +{file.additions}/-{file.deletions}")
360
```
361

362
### Issue Management
363
```python
364
# Bulk operations on issues
365
org_issues = list(gh.organization_issues('my-org', state='open'))
366

367
# Find stale issues
368
import datetime
369
cutoff = datetime.datetime.now() - datetime.timedelta(days=30)
370
stale_issues = [i for i in org_issues if i.updated_at < cutoff]
371

372
print(f"Found {len(stale_issues)} stale issues")
373
```
374

375
### Advanced Filtering
376
```python
377
# Complex issue queries
378
# Issues assigned to multiple people
379
multi_assigned = gh.issues_on(
380
    'owner', 'repo',
381
    assignee='*',  # Any assignee
382
    labels='priority-high,bug'
383
)
384

385
# Recent issues with activity
386
recent = gh.issues_on(
387
    'owner', 'repo',
388
    since=datetime.datetime.now() - datetime.timedelta(days=7),
389
    sort='updated'
390
)
391
```