0
# CI/CD Integration
1

2
Classes and utilities for integrating semgrep into various continuous integration and deployment platforms with automatic metadata detection.
3

4
## Capabilities
5

6
### Base CI/CD Classes
7

8
Foundation classes for CI/CD platform integration.
9

10
```python { .api }
11
class GitMeta:
12
    """
13
    Base Git repository metadata class.
14
    
15
    Provides common functionality for extracting Git repository
16
    information across different CI/CD platforms.
17
    
18
    Attributes:
19
    - branch (str): Current branch name
20
    - commit_sha (str): Current commit SHA
21
    - commit_message (str): Current commit message
22
    - commit_timestamp (str): Commit timestamp
23
    - commit_author_name (str): Commit author name
24
    - commit_author_email (str): Commit author email
25
    - repository_name (str): Repository name
26
    - repository_url (str): Repository URL
27
    """
28
    def __init__(self): ...
29
    
30
    def get_branch(self): ...
31
    def get_commit_sha(self): ...
32
    def get_commit_message(self): ...
33
    def get_repository_info(self): ...
34
    def is_pull_request(self): ...
35
```
36

37
### Platform-Specific Integration Classes
38

39
Specialized classes for each CI/CD platform with automatic environment detection.
40

41
```python { .api }
42
class GithubMeta(GitMeta):
43
    """
44
    GitHub Actions CI integration.
45
    
46
    Automatically detects GitHub Actions environment and extracts
47
    relevant metadata from GitHub-specific environment variables.
48
    
49
    Additional Attributes:
50
    - pull_request_number (str): PR number if applicable
51
    - github_actor (str): GitHub username triggering the action
52
    - workflow_name (str): GitHub workflow name
53
    - job_name (str): Current job name
54
    - run_id (str): GitHub Actions run ID
55
    """
56
    def __init__(self): ...
57
    
58
    def get_pull_request_info(self): ...
59
    def get_workflow_context(self): ...
60
    def get_github_token(self): ...
61

62
class GitlabMeta(GitMeta):
63
    """
64
    GitLab CI integration.
65
    
66
    Extracts metadata from GitLab CI/CD environment variables
67
    and provides GitLab-specific functionality.
68
    
69
    Additional Attributes:
70
    - pipeline_id (str): GitLab pipeline ID
71
    - job_id (str): GitLab job ID
72
    - merge_request_iid (str): Merge request internal ID
73
    - project_id (str): GitLab project ID
74
    - runner_id (str): GitLab runner ID
75
    """
76
    def __init__(self): ...
77
    
78
    def get_merge_request_info(self): ...
79
    def get_pipeline_context(self): ...
80
    def get_project_info(self): ...
81

82
class CircleCIMeta(GitMeta):
83
    """
84
    CircleCI integration.
85
    
86
    Handles CircleCI-specific environment variables and provides
87
    CircleCI workflow and job context.
88
    
89
    Additional Attributes:
90
    - build_number (str): CircleCI build number
91
    - workflow_id (str): CircleCI workflow ID
92
    - job_name (str): CircleCI job name
93
    - node_index (str): Parallel job node index
94
    """
95
    def __init__(self): ...
96
    
97
    def get_build_info(self): ...
98
    def get_workflow_info(self): ...
99
    def is_parallel_job(self): ...
100

101
class JenkinsMeta(GitMeta):
102
    """
103
    Jenkins CI integration.
104
    
105
    Extracts metadata from Jenkins environment variables
106
    and provides Jenkins-specific build context.
107
    
108
    Additional Attributes:
109
    - build_number (str): Jenkins build number
110
    - build_id (str): Jenkins build ID
111
    - job_name (str): Jenkins job name
112
    - workspace (str): Jenkins workspace path
113
    """
114
    def __init__(self): ...
115
    
116
    def get_build_info(self): ...
117
    def get_job_context(self): ...
118
    def get_workspace_info(self): ...
119

120
class BitbucketMeta(GitMeta):
121
    """
122
    Bitbucket Pipelines integration.
123
    
124
    Handles Bitbucket Pipelines environment and provides
125
    repository and pipeline context.
126
    
127
    Additional Attributes:
128
    - build_number (str): Bitbucket build number
129
    - step_triggerer_uuid (str): User UUID who triggered the step
130
    - pipeline_uuid (str): Pipeline UUID
131
    - workspace (str): Bitbucket workspace
132
    """
133
    def __init__(self): ...
134
    
135
    def get_pipeline_info(self): ...
136
    def get_workspace_info(self): ...
137

138
class AzurePipelinesMeta(GitMeta):
139
    """
140
    Azure Pipelines integration.
141
    
142
    Extracts metadata from Azure DevOps Pipelines environment
143
    and provides pipeline and build context.
144
    
145
    Additional Attributes:
146
    - build_id (str): Azure build ID
147
    - build_number (str): Azure build number
148
    - pipeline_name (str): Pipeline name
149
    - stage_name (str): Current stage name
150
    - job_name (str): Current job name
151
    """
152
    def __init__(self): ...
153
    
154
    def get_build_context(self): ...
155
    def get_pipeline_context(self): ...
156

157
class BuildkiteMeta(GitMeta):
158
    """
159
    Buildkite CI integration.
160
    
161
    Handles Buildkite-specific environment variables and provides
162
    build and pipeline context.
163
    
164
    Additional Attributes:
165
    - build_number (str): Buildkite build number
166
    - pipeline_slug (str): Pipeline slug identifier
167
    - agent_name (str): Buildkite agent name
168
    - job_id (str): Buildkite job ID
169
    """
170
    def __init__(self): ...
171
    
172
    def get_build_info(self): ...
173
    def get_agent_info(self): ...
174

175
class TravisMeta(GitMeta):
176
    """
177
    Travis CI integration.
178
    
179
    Extracts metadata from Travis CI environment variables
180
    and provides build context.
181
    
182
    Additional Attributes:
183
    - build_number (str): Travis build number
184
    - job_number (str): Travis job number
185
    - build_id (str): Travis build ID
186
    - job_id (str): Travis job ID
187
    """
188
    def __init__(self): ...
189
    
190
    def get_build_info(self): ...
191
    def get_job_info(self): ...
192
```
193

194
### Platform Detection
195

196
Utility functions for automatic CI/CD platform detection.
197

198
```python { .api }
199
def detect_ci_platform():
200
    """
201
    Automatically detect the current CI/CD platform.
202
    
203
    Examines environment variables to determine which
204
    CI/CD platform is currently running.
205
    
206
    Returns:
207
    str: Platform name (github, gitlab, circleci, jenkins, etc.)
208
    None: If no known platform is detected
209
    """
210

211
def get_platform_metadata(platform_name=None):
212
    """
213
    Get metadata for the specified or detected platform.
214
    
215
    Parameters:
216
    - platform_name (str, optional): Specific platform to get metadata for
217
                                    If None, auto-detects platform
218
    
219
    Returns:
220
    GitMeta: Platform-specific metadata object
221
    None: If platform not supported or detected
222
    """
223

224
def is_ci_environment():
225
    """
226
    Check if code is running in a CI/CD environment.
227
    
228
    Returns:
229
    bool: True if running in a detected CI environment
230
    """
231
```
232

233
## Usage Examples
234

235
### Automatic Platform Detection
236

237
```python
238
from semgrep.meta import detect_ci_platform, get_platform_metadata
239

240
# Auto-detect CI platform
241
platform = detect_ci_platform()
242
print(f"Detected platform: {platform}")
243

244
# Get platform metadata
245
if platform:
246
    meta = get_platform_metadata(platform)
247
    print(f"Branch: {meta.get_branch()}")
248
    print(f"Commit: {meta.get_commit_sha()}")
249
    print(f"Repository: {meta.get_repository_info()}")
250
```
251

252
### Platform-Specific Usage
253

254
```python
255
from semgrep.meta import GithubMeta, GitlabMeta
256

257
# GitHub-specific usage
258
if detect_ci_platform() == "github":
259
    github_meta = GithubMeta()
260
    
261
    if github_meta.is_pull_request():
262
        pr_info = github_meta.get_pull_request_info()
263
        print(f"PR #{pr_info['number']}: {pr_info['title']}")
264
    
265
    workflow_context = github_meta.get_workflow_context()
266
    print(f"Workflow: {workflow_context['workflow_name']}")
267
    print(f"Job: {workflow_context['job_name']}")
268

269
# GitLab-specific usage  
270
elif detect_ci_platform() == "gitlab":
271
    gitlab_meta = GitlabMeta()
272
    
273
    pipeline_context = gitlab_meta.get_pipeline_context()
274
    print(f"Pipeline ID: {pipeline_context['pipeline_id']}")
275
    
276
    if gitlab_meta.is_pull_request():  # Merge request in GitLab
277
        mr_info = gitlab_meta.get_merge_request_info()
278
        print(f"MR !{mr_info['iid']}: {mr_info['title']}")
279
```
280

281
### Custom Integration
282

283
```python
284
from semgrep.meta import GitMeta
285

286
class CustomCIMeta(GitMeta):
287
    """Custom CI platform integration."""
288
    
289
    def __init__(self):
290
        super().__init__()
291
        self.custom_build_id = os.getenv("CUSTOM_BUILD_ID")
292
        self.custom_environment = os.getenv("CUSTOM_ENV")
293
    
294
    def get_custom_context(self):
295
        return {
296
            "build_id": self.custom_build_id,
297
            "environment": self.custom_environment,
298
            "branch": self.get_branch(),
299
            "commit": self.get_commit_sha()
300
        }
301

302
# Usage
303
custom_meta = CustomCIMeta()
304
context = custom_meta.get_custom_context()
305
print(f"Custom build context: {context}")
306
```