0
# GitHub Apps & Checks
1

2
GitHub Apps integration including installation management, check runs, check suites, and status checks for CI/CD integrations.
3

4
## Capabilities
5

6
### GitHub Apps
7

8
Managing GitHub Apps and their installations.
9

10
```python { .api }
11
class GitHub:
12
    def app(self):
13
        """
14
        Get the authenticated GitHub App.
15
        
16
        Returns:
17
            App: GitHub App object
18
        """
19

20
    def app_installation(self, installation_id):
21
        """
22
        Get a GitHub App installation.
23
        
24
        Args:
25
            installation_id (int): Installation ID
26
            
27
        Returns:
28
            Installation: Installation object
29
        """
30

31
    def app_installations(self):
32
        """
33
        List installations for the authenticated GitHub App.
34
        
35
        Returns:
36
            iterator: Iterator of Installation objects
37
        """
38

39
    def app_installation_for_repository(self, owner, repository):
40
        """
41
        Get the installation for a specific repository.
42
        
43
        Args:
44
            owner (str): Repository owner
45
            repository (str): Repository name
46
            
47
        Returns:
48
            Installation: Installation object or None
49
        """
50
```
51

52
### Check Runs
53

54
Managing individual check runs for commits.
55

56
```python { .api }
57
class Repository:
58
    def check_runs_for_ref(self, ref, check_name=None, status=None, filter="latest"):
59
        """
60
        List check runs for a reference.
61
        
62
        Args:
63
            ref (str): Git reference (SHA, branch, tag)
64
            check_name (str, optional): Filter by check name
65
            status (str, optional): Filter by status ('queued', 'in_progress', 'completed')
66
            filter (str): Filter type ('latest', 'all')
67
            
68
        Returns:
69
            iterator: Iterator of CheckRun objects
70
        """
71

72
    def check_run(self, check_run_id):
73
        """
74
        Get a specific check run.
75
        
76
        Args:
77
            check_run_id (int): Check run ID
78
            
79
        Returns:
80
            CheckRun: Check run object or None
81
        """
82

83
    def create_check_run(self, name, head_sha, status="queued", external_id=None, 
84
                        started_at=None, conclusion=None, completed_at=None, 
85
                        output=None, actions=None):
86
        """
87
        Create a check run.
88
        
89
        Args:
90
            name (str): Check run name
91
            head_sha (str): SHA of the commit
92
            status (str): Status ('queued', 'in_progress', 'completed')
93
            external_id (str, optional): External identifier
94
            started_at (str, optional): Start time (ISO 8601)
95
            conclusion (str, optional): Conclusion ('success', 'failure', 'neutral', 'cancelled', 'timed_out', 'action_required')
96
            completed_at (str, optional): Completion time (ISO 8601)
97
            output (dict, optional): Check run output
98
            actions (list, optional): Actions that can be performed
99
            
100
        Returns:
101
            CheckRun: Created check run object
102
        """
103

104
class CheckRun:
105
    def update(self, status=None, conclusion=None, completed_at=None, output=None, actions=None):
106
        """
107
        Update this check run.
108
        
109
        Args:
110
            status (str, optional): New status
111
            conclusion (str, optional): New conclusion
112
            completed_at (str, optional): Completion time
113
            output (dict, optional): Check run output
114
            actions (list, optional): Available actions
115
            
116
        Returns:
117
            bool: True if successful
118
        """
119
```
120

121
### Check Suites
122

123
Managing check suites (collections of check runs).
124

125
```python { .api }
126
class Repository:
127
    def check_suites_for_ref(self, ref, app_id=None, check_name=None):
128
        """
129
        List check suites for a reference.
130
        
131
        Args:
132
            ref (str): Git reference (SHA, branch, tag)
133
            app_id (int, optional): Filter by GitHub App ID
134
            check_name (str, optional): Filter by check name
135
            
136
        Returns:
137
            iterator: Iterator of CheckSuite objects
138
        """
139

140
    def check_suite(self, check_suite_id):
141
        """
142
        Get a specific check suite.
143
        
144
        Args:
145
            check_suite_id (int): Check suite ID
146
            
147
        Returns:
148
            CheckSuite: Check suite object or None
149
        """
150

151
    def create_check_suite(self, head_sha):
152
        """
153
        Create a check suite.
154
        
155
        Args:
156
            head_sha (str): SHA of the commit
157
            
158
        Returns:
159
            CheckSuite: Created check suite object
160
        """
161

162
class CheckSuite:
163
    def rerequest(self):
164
        """
165
        Re-request this check suite.
166
        
167
        Returns:
168
            bool: True if successful
169
        """
170

171
    def check_runs(self, check_name=None, status=None, filter="latest"):
172
        """
173
        List check runs in this suite.
174
        
175
        Args:
176
            check_name (str, optional): Filter by check name
177
            status (str, optional): Filter by status
178
            filter (str): Filter type ('latest', 'all')
179
            
180
        Returns:
181
            iterator: Iterator of CheckRun objects
182
        """
183
```
184

185
### Status Checks (Legacy)
186

187
Legacy commit status API (superseded by check runs).
188

189
```python { .api }
190
class Repository:
191
    def statuses(self, sha):
192
        """
193
        List statuses for a commit.
194
        
195
        Args:
196
            sha (str): Commit SHA
197
            
198
        Returns:
199
            iterator: Iterator of status objects
200
        """
201

202
    def combined_status(self, sha):
203
        """
204
        Get combined status for a commit.
205
        
206
        Args:
207
            sha (str): Commit SHA
208
            
209
        Returns:
210
            dict: Combined status information
211
        """
212

213
    def create_status(self, sha, state, target_url=None, description=None, context="default"):
214
        """
215
        Create a status for a commit.
216
        
217
        Args:
218
            sha (str): Commit SHA
219
            state (str): Status state ('pending', 'success', 'error', 'failure')
220
            target_url (str, optional): Target URL
221
            description (str, optional): Status description
222
            context (str): Status context
223
            
224
        Returns:
225
            dict: Created status object
226
        """
227
```
228

229
## Model Classes
230

231
```python { .api }
232
class App:
233
    """GitHub App information."""
234
    id: int
235
    slug: str
236
    name: str
237
    owner: 'User'
238
    description: str
239
    external_url: str
240
    html_url: str
241
    created_at: str
242
    updated_at: str
243
    permissions: dict
244
    events: list
245
    installations_count: int
246

247
class Installation:
248
    """GitHub App installation."""
249
    id: int
250
    account: 'User'  # User or Organization
251
    repository_selection: str  # 'selected' or 'all'
252
    access_tokens_url: str
253
    repositories_url: str
254
    html_url: str
255
    app_id: int
256
    app_slug: str
257
    target_id: int
258
    target_type: str
259
    permissions: dict
260
    events: list
261
    created_at: str
262
    updated_at: str
263
    single_file_name: str
264
    has_multiple_single_files: bool
265
    single_file_paths: list
266

267
class CheckSuite:
268
    """Check suite (collection of check runs)."""
269
    id: int
270
    head_branch: str
271
    head_sha: str
272
    status: str  # 'queued', 'in_progress', 'completed'
273
    conclusion: str  # 'success', 'failure', 'neutral', 'cancelled', 'timed_out', 'action_required'
274
    url: str
275
    before: str
276
    after: str
277
    pull_requests: list
278
    app: 'CheckApp'
279
    repository: 'Repository'
280
    created_at: str
281
    updated_at: str
282
    
283
    def rerequest(self): ...
284
    def check_runs(self): ...
285

286
class CheckRun:
287
    """Individual check run."""
288
    id: int
289
    head_sha: str
290
    external_id: str
291
    url: str
292
    html_url: str
293
    details_url: str
294
    status: str  # 'queued', 'in_progress', 'completed'
295
    conclusion: str  # 'success', 'failure', 'neutral', 'cancelled', 'timed_out', 'action_required'
296
    started_at: str
297
    completed_at: str
298
    output: 'CheckRunOutput'
299
    name: str
300
    check_suite: 'CheckSuite'
301
    app: 'CheckApp'
302
    pull_requests: list
303
    
304
    def update(self, **kwargs): ...
305

306
class CheckRunOutput:
307
    """Check run output details."""
308
    title: str
309
    summary: str
310
    text: str
311
    annotations_count: int
312
    annotations_url: str
313
    annotations: list  # List of CheckRunAnnotation
314

315
class CheckRunAnnotation:
316
    """Annotation in check run output."""
317
    path: str
318
    start_line: int
319
    end_line: int
320
    start_column: int
321
    end_column: int
322
    annotation_level: str  # 'notice', 'warning', 'failure'
323
    message: str
324
    title: str
325
    raw_details: str
326

327
class CheckPullRequest:
328
    """Pull request in check context."""
329
    url: str
330
    id: int
331
    number: int
332
    head: dict
333
    base: dict
334

335
class CheckApp:
336
    """App in check context."""
337
    id: int
338
    slug: str
339
    name: str
340
    owner: 'User'
341
```
342

343
## Usage Examples
344

345
### Creating Check Runs
346

347
```python
348
import github3
349

350
# Authenticate as GitHub App installation
351
gh = github3.GitHub()
352
gh.login_as_app_installation(private_key, app_id, installation_id)
353

354
repo = gh.repository('owner', 'repo')
355

356
# Create a check run
357
check_run = repo.create_check_run(
358
    name='My CI Check',
359
    head_sha='commit_sha_here',
360
    status='in_progress',
361
    started_at='2023-01-01T10:00:00Z',
362
    output={
363
        'title': 'Running tests',
364
        'summary': 'Running unit tests and linting',
365
        'text': 'This check will validate code quality'
366
    }
367
)
368

369
# Update the check run when complete
370
check_run.update(
371
    status='completed',
372
    conclusion='success',
373
    completed_at='2023-01-01T10:05:00Z',
374
    output={
375
        'title': 'All tests passed',
376
        'summary': 'All 42 tests passed successfully',
377
        'text': 'Code coverage: 95%\nLinting: No issues found'
378
    }
379
)
380
```
381

382
### Managing Check Suites
383

384
```python
385
# List check suites for a commit
386
for suite in repo.check_suites_for_ref('commit_sha'):
387
    print(f"Suite {suite.id}: {suite.status} ({suite.conclusion})")
388
    
389
    # List check runs in the suite
390
    for run in suite.check_runs():
391
        print(f"  - {run.name}: {run.status} ({run.conclusion})")
392

393
# Re-request a check suite
394
suite.rerequest()
395
```
396

397
### Legacy Status API
398

399
```python
400
# Create a commit status (legacy API)
401
status = repo.create_status(
402
    sha='commit_sha',
403
    state='success',
404
    target_url='https://ci.example.com/builds/123',
405
    description='Build succeeded',
406
    context='continuous-integration/travis-ci'
407
)
408

409
# Get combined status
410
combined = repo.combined_status('commit_sha')
411
print(f"Overall state: {combined['state']}")
412
for status in combined['statuses']:
413
    print(f"  {status['context']}: {status['state']}")
414
```