0
# Apache Airflow Providers GitHub
1

2
Apache Airflow provider package for seamless GitHub integration through hooks, operators, and sensors. Enables GitHub repository management, issue tracking, pull request automation, and workflow orchestration within Apache Airflow DAGs using the PyGithub SDK.
3

4
## Package Information
5

6
- **Package Name**: apache-airflow-providers-github
7
- **Language**: Python
8
- **Installation**: `pip install apache-airflow-providers-github`
9
- **Dependencies**: `apache-airflow>=2.10.0`, `PyGithub>=2.1.1`
10

11
## Core Imports
12

13
```python
14
from airflow.providers.github.hooks.github import GithubHook
15
from airflow.providers.github.operators.github import GithubOperator
16
from airflow.providers.github.sensors.github import GithubSensor, GithubTagSensor, BaseGithubRepositorySensor
17
from airflow.providers.github.get_provider_info import get_provider_info
18
from airflow.providers.github import __version__
19
```
20

21
## Basic Usage
22

23
```python
24
from datetime import datetime
25
from airflow import DAG
26
from airflow.providers.github.hooks.github import GithubHook
27
from airflow.providers.github.operators.github import GithubOperator
28
from airflow.providers.github.sensors.github import GithubTagSensor
29

30
# Create a DAG
31
dag = DAG(
32
    'github_example',
33
    start_date=datetime(2024, 1, 1),
34
    schedule_interval='@daily',
35
    catchup=False
36
)
37

38
# Use the hook to connect to GitHub
39
hook = GithubHook(github_conn_id='github_default')
40
client = hook.get_conn()
41
user = client.get_user()
42

43
# Use an operator to list repositories
44
list_repos = GithubOperator(
45
    task_id='list_repositories',
46
    github_method='get_user',
47
    result_processor=lambda user: [repo.name for repo in user.get_repos()],
48
    dag=dag
49
)
50

51
# Use a sensor to monitor for a tag
52
wait_for_tag = GithubTagSensor(
53
    task_id='wait_for_v1_release',
54
    repository_name='apache/airflow',
55
    tag_name='v1.0',
56
    timeout=300,
57
    dag=dag
58
)
59
```
60

61
## Architecture
62

63
The GitHub provider follows Apache Airflow's standard provider architecture:
64

65
- **Hooks**: Handle authentication and connection management to GitHub API
66
- **Operators**: Execute GitHub operations as Airflow tasks
67
- **Sensors**: Monitor GitHub resources and trigger downstream tasks
68
- **Connection Types**: Define GitHub connection configuration in Airflow UI
69

70
All components use PyGithub as the underlying GitHub SDK and follow Airflow's templating, logging, and error handling patterns.
71

72
## Capabilities
73

74
### GitHub Connection Management
75

76
Establishes and manages authenticated connections to GitHub API using tokens, with support for GitHub Enterprise through custom base URLs.
77

78
```python { .api }
79
class GithubHook(BaseHook):
80
    def __init__(self, github_conn_id: str = "github_default", *args, **kwargs) -> None: ...
81
    def get_conn(self) -> GithubClient: ...
82
    def test_connection(self) -> tuple[bool, str]: ...
83
```
84

85
[GitHub Hooks](./hooks.md)
86

87
### GitHub Operations
88

89
Execute arbitrary GitHub API operations through PyGithub methods, with support for result processing and templated parameters.
90

91
```python { .api }
92
class GithubOperator(BaseOperator):
93
    def __init__(
94
        self,
95
        *,
96
        github_method: str,
97
        github_conn_id: str = "github_default",
98
        github_method_args: dict | None = None,
99
        result_processor: Callable | None = None,
100
        **kwargs,
101
    ) -> None: ...
102
    def execute(self, context: Context) -> Any: ...
103
```
104

105
[GitHub Operators](./operators.md)
106

107
### GitHub Monitoring
108

109
Monitor GitHub resources for changes and trigger downstream tasks based on repository events, tag creation, or custom conditions.
110

111
```python { .api }
112
class GithubSensor(BaseSensorOperator):
113
    def __init__(
114
        self,
115
        *,
116
        method_name: str,
117
        github_conn_id: str = "github_default",
118
        method_params: dict | None = None,
119
        result_processor: Callable | None = None,
120
        **kwargs,
121
    ) -> None: ...
122
    def poke(self, context: Context) -> bool: ...
123

124
class GithubTagSensor(BaseGithubRepositorySensor):
125
    def __init__(
126
        self,
127
        *,
128
        github_conn_id: str = "github_default",
129
        tag_name: str | None = None,
130
        repository_name: str | None = None,
131
        **kwargs,
132
    ) -> None: ...
133
    def poke(self, context: Context) -> bool: ...
134
```
135

136
[GitHub Sensors](./sensors.md)
137

138
### Provider Metadata
139

140
Access provider information and registration details through the provider info function.
141

142
```python { .api }
143
def get_provider_info() -> dict:
144
    """
145
    Return provider metadata dictionary.
146
    
147
    Returns comprehensive provider information including hooks, operators,
148
    sensors, and connection types for Airflow provider registration.
149
    
150
    Returns:
151
    dict: Provider metadata with integration details
152
    """
153
```
154

155
## Connection Configuration
156

157
Configure GitHub connections in Airflow:
158

159
- **Connection Type**: `github`
160
- **Connection ID**: `github_default` (default)
161
- **Password**: GitHub Personal Access Token (required)
162
- **Host**: GitHub Enterprise base URL (optional, format: `https://{hostname}/api/v3`)
163

164
## Types
165

166
```python { .api }
167
from typing import Any, TYPE_CHECKING
168
from collections.abc import Callable
169
from github import Github as GithubClient, GithubException
170
from airflow.exceptions import AirflowException
171
from airflow.providers.github.version_compat import (
172
    Context, BaseHook, BaseOperator, BaseSensorOperator,
173
    AIRFLOW_V_3_0_PLUS, AIRFLOW_V_3_1_PLUS
174
)
175

176
# Type aliases used throughout the package
177
Context = Context  # Airflow execution context
178
GithubClient = GithubClient  # PyGithub client instance
179

180
# Exception types
181
GithubException = GithubException  # PyGithub API exceptions
182
AirflowException = AirflowException  # Airflow framework exceptions
183

184
# Version-compatible base classes
185
BaseHook = BaseHook  # Base hook class (version-dependent import)
186
BaseOperator = BaseOperator  # Base operator class (version-dependent import)  
187
BaseSensorOperator = BaseSensorOperator  # Base sensor class (version-dependent import)
188

189
# Version detection constants
190
AIRFLOW_V_3_0_PLUS = AIRFLOW_V_3_0_PLUS  # Boolean for Airflow 3.0+ compatibility
191
AIRFLOW_V_3_1_PLUS = AIRFLOW_V_3_1_PLUS  # Boolean for Airflow 3.1+ compatibility
192

193
# Package version
194
__version__ = "2.9.2"  # Package version string
195
```