0
# GitHub Hooks
1

2
GitHub Hook provides authenticated connection management to GitHub API using PyGithub client. Handles authentication, connection caching, and provides access to the full GitHub API surface through the PyGithub SDK.
3

4
## Capabilities
5

6
### GithubHook
7

8
Main hook class for GitHub API integration that manages authentication and client lifecycle.
9

10
```python { .api }
11
class GithubHook(BaseHook):
12
    """
13
    Interact with GitHub API through PyGithub client.
14
    
15
    Performs connection to GitHub and retrieves authenticated client.
16
    Supports GitHub.com and GitHub Enterprise installations.
17
    """
18
    
19
    # Class attributes
20
    conn_name_attr: str = "github_conn_id"
21
    default_conn_name: str = "github_default"
22
    conn_type: str = "github"
23
    hook_name: str = "GitHub"
24
    
25
    def __init__(self, github_conn_id: str = "github_default", *args, **kwargs) -> None:
26
        """
27
        Initialize GitHub hook and establish connection.
28
        
29
        Automatically calls get_conn() to initialize the client connection.
30
        
31
        Parameters:
32
        - github_conn_id: Reference to GitHub connection ID configured in Airflow
33
        """
34
    
35
    def get_conn(self) -> GithubClient:
36
        """
37
        Initiate a new GitHub connection with token and hostname (for GitHub Enterprise).
38
        
39
        Uses connection configuration to authenticate with GitHub API.
40
        Caches client instance for reuse within the same hook instance.
41
        Sets self.client attribute with the authenticated client.
42
        
43
        Returns:
44
        GithubClient: Authenticated PyGithub client instance
45
        
46
        Raises:
47
        AirflowException: If access token is not provided in connection
48
        """
49
    
50
    @property
51
    def client(self) -> GithubClient:
52
        """
53
        Access the cached GitHub client instance.
54
        
55
        Returns the client initialized by get_conn() method.
56
        
57
        Returns:
58
        GithubClient: Authenticated PyGithub client instance
59
        """
60
    
61
    def test_connection(self) -> tuple[bool, str]:
62
        """
63
        Test GitHub connection by attempting to retrieve user information.
64
        
65
        Returns:
66
        tuple[bool, str]: (success_status, message)
67
        """
68
    
69
    @classmethod
70
    def get_ui_field_behaviour(cls) -> dict:
71
        """
72
        Return custom field behaviour for Airflow connection UI.
73
        
74
        Configures which fields are hidden, relabeled, or have placeholders
75
        in the Airflow connection form.
76
        
77
        Returns:
78
        dict: UI field configuration
79
        """
80
```
81

82
## Usage Examples
83

84
### Basic Hook Usage
85

86
```python
87
from airflow.providers.github.hooks.github import GithubHook
88

89
# Create hook with default connection
90
hook = GithubHook()
91

92
# Get authenticated client
93
client = hook.get_conn()
94

95
# Use PyGithub client directly
96
user = client.get_user()
97
repos = list(user.get_repos())
98

99
# Access specific repository
100
repo = client.get_repo("apache/airflow")
101
issues = list(repo.get_issues(state='open'))
102
```
103

104
### Custom Connection ID
105

106
```python
107
# Use specific connection ID
108
hook = GithubHook(github_conn_id='github_prod')
109
client = hook.get_conn()
110

111
# Test connection
112
success, message = hook.test_connection()
113
if success:
114
    print("Connection successful")
115
else:
116
    print(f"Connection failed: {message}")
117
```
118

119
### GitHub Enterprise Usage
120

121
```python
122
# Configure connection in Airflow UI:
123
# - Connection Type: github
124
# - Connection ID: github_enterprise
125
# - Password: your_access_token
126
# - Host: https://github.enterprise.com/api/v3
127

128
hook = GithubHook(github_conn_id='github_enterprise')
129
client = hook.get_conn()
130

131
# Client now points to enterprise instance
132
enterprise_user = client.get_user()
133
```
134

135
## Connection Configuration Details
136

137
### Required Fields
138
- **Password**: GitHub Personal Access Token or GitHub App token
139

140
### Optional Fields  
141
- **Host**: GitHub Enterprise base URL (format: `https://{hostname}/api/v3`)
142

143
### Hidden Fields
144
- schema, port, login, extra (not used by GitHub provider)
145

146
### Field Labels in UI
147
- **Host**: "GitHub Enterprise URL (Optional)"
148
- **Password**: "GitHub Access Token"
149

150
## Error Handling
151

152
The hook wraps PyGithub exceptions as `AirflowException`:
153

154
```python
155
try:
156
    hook = GithubHook()
157
    client = hook.get_conn()
158
    # Operations that may fail
159
    repo = client.get_repo("nonexistent/repo")
160
except AirflowException as e:
161
    # Handle Airflow-wrapped GitHub errors
162
    print(f"GitHub operation failed: {e}")
163
```