0
# Python-GitLab
1

2
A comprehensive Python wrapper for GitLab's REST and GraphQL APIs, enabling developers to programmatically interact with GitLab repositories, projects, users, issues, merge requests, and other GitLab resources. The library provides both synchronous and asynchronous GraphQL API clients along with a command-line interface.
3

4
## Package Information
5

6
- **Package Name**: python-gitlab
7
- **Language**: Python
8
- **Installation**: `pip install python-gitlab`
9
- **Minimum Python Version**: 3.9+
10

11
## Core Imports
12

13
```python
14
import gitlab
15
```
16

17
Main client access:
18

19
```python
20
from gitlab import Gitlab, GitlabList
21
```
22

23
GraphQL clients:
24

25
```python
26
from gitlab import GraphQL, AsyncGraphQL
27
```
28

29
Exception handling:
30

31
```python
32
from gitlab import GitlabError, GitlabAuthenticationError
33
```
34

35
## Basic Usage
36

37
```python
38
import gitlab
39

40
# Connect to GitLab instance
41
gl = gitlab.Gitlab("https://gitlab.example.com", private_token="your-token")
42

43
# Get current user
44
user = gl.auth()
45
print(f"Logged in as: {user.name}")
46

47
# List all projects
48
projects = gl.projects.list(all=True)
49

50
# Get a specific project
51
project = gl.projects.get(123)
52
print(f"Project: {project.name}")
53

54
# Create an issue
55
issue = project.issues.create({
56
    'title': 'New issue', 
57
    'description': 'Issue description'
58
})
59

60
# List merge requests
61
mrs = project.mergerequests.list(state='opened')
62
for mr in mrs:
63
    print(f"MR: {mr.title}")
64
```
65

66
## Architecture
67

68
Python-GitLab follows a consistent object-manager pattern:
69

70
- **Gitlab Client**: Main entry point providing authentication and server configuration
71
- **Manager Classes**: Handle CRUD operations for specific resource types (e.g., ProjectManager, UserManager)
72
- **Resource Objects**: Represent individual GitLab entities (e.g., Project, User, Issue)
73
- **Mixins**: Provide reusable functionality patterns for common operations
74
- **GraphQL Clients**: Handle GraphQL API interactions with query execution and error handling
75

76
The library uses a lazy loading approach where resource objects and nested managers are created on-demand, providing efficient memory usage and flexible API access patterns.
77

78
## Capabilities
79

80
### Client Configuration and Authentication
81

82
Core client setup, authentication methods, configuration management, and server connectivity. Supports multiple authentication methods including private tokens, OAuth tokens, and CI job tokens.
83

84
```python { .api }
85
class Gitlab:
86
    def __init__(
87
        self,
88
        url: str | None = None,
89
        private_token: str | None = None,
90
        oauth_token: str | None = None,
91
        job_token: str | None = None,
92
        ssl_verify: bool | str = True,
93
        timeout: float | None = None,
94
        **kwargs
95
    ) -> None: ...
96
    
97
    def auth(self) -> None: ...
98
    def version(self) -> tuple[str, str]: ...
99
```
100

101
[Client and Authentication](./client-auth.md)
102

103
### Project Management
104

105
Comprehensive project lifecycle management including creation, configuration, access control, and administrative operations. Covers project settings, members, access tokens, and project-level resources.
106

107
```python { .api }
108
class Project:
109
    def save(self) -> None: ...
110
    def delete(self) -> None: ...
111
    def transfer_project(self, to_namespace: str) -> dict: ...
112
    def fork(self, namespace: str | None = None) -> dict: ...
113
    
114
class ProjectManager:
115
    def list(self, **kwargs) -> list[Project]: ...
116
    def get(self, id: int, **kwargs) -> Project: ...
117
    def create(self, data: dict, **kwargs) -> Project: ...
118
```
119

120
[Project Management](./projects.md)
121

122
### User and Group Management  
123

124
User account management, group administration, membership control, and access level configuration. Includes user profiles, SSH keys, GPG keys, and group hierarchies.
125

126
```python { .api }
127
class User:
128
    def save(self) -> None: ...
129
    def delete(self) -> None: ...
130
    def block(self) -> dict: ...
131
    def unblock(self) -> dict: ...
132
    
133
class Group:
134
    def save(self) -> None: ...
135
    def delete(self) -> None: ...
136
    def transfer(self, to_namespace: str) -> dict: ...
137
```
138

139
[Users and Groups](./users-groups.md)
140

141
### Issues and Merge Requests
142

143
Issue tracking, merge request workflows, code review processes, and collaborative development features. Covers issue management, MR approvals, discussions, and state transitions.
144

145
```python { .api }
146
class ProjectIssue:
147
    def save(self) -> None: ...
148
    def subscribe(self) -> dict: ...
149
    def unsubscribe(self) -> dict: ...
150
    
151
class ProjectMergeRequest:
152
    def save(self) -> None: ...
153
    def merge(self, **kwargs) -> dict: ...
154
    def approve(self) -> dict: ...
155
    def unapprove(self) -> dict: ...
156
```
157

158
[Issues and Merge Requests](./issues-mrs.md)
159

160
### CI/CD Pipeline Management
161

162
Continuous integration and deployment pipeline control, job management, runner administration, and artifact handling. Includes pipeline triggers, variables, and deployment environments.
163

164
```python { .api }
165
class ProjectPipeline:
166
    def cancel(self) -> dict: ...
167
    def retry(self) -> dict: ...
168
    def play(self) -> dict: ...
169
    
170
class ProjectJob:
171
    def cancel(self) -> dict: ...
172
    def retry(self) -> dict: ...
173
    def play(self) -> dict: ...
174
    def erase(self) -> dict: ...
175
```
176

177
[CI/CD Management](./cicd.md)
178

179
### Repository and Code Management
180

181
Git repository operations, branch management, commit handling, file operations, and version control workflows. Covers repository files, branches, tags, and commit operations.
182

183
```python { .api }
184
class ProjectCommit:
185
    def cherry_pick(self, branch: str) -> dict: ...
186
    def revert(self, branch: str) -> dict: ...
187
    
188
class ProjectBranch:
189
    def protect(self, **kwargs) -> dict: ...
190
    def unprotect(self) -> dict: ...
191
    
192
class ProjectFile:
193
    def save(self) -> None: ...
194
    def delete(self) -> None: ...
195
```
196

197
[Repository Management](./repository.md)
198

199
### GraphQL API Access
200

201
Advanced GraphQL query execution with both synchronous and asynchronous clients. Provides flexible querying capabilities and efficient data fetching for complex GitLab API interactions.
202

203
```python { .api }
204
class GraphQL:
205
    def execute(self, query: str, variables: dict | None = None) -> dict: ...
206
    
207
class AsyncGraphQL:
208
    async def execute(self, query: str, variables: dict | None = None) -> dict: ...
209
```
210

211
[GraphQL Clients](./graphql.md)
212

213
## Error Handling
214

215
```python { .api }
216
class GitlabError(Exception):
217
    def __init__(
218
        self,
219
        error_message: str | bytes = "",
220
        response_code: int | None = None,
221
        response_body: bytes | None = None,
222
    ) -> None: ...
223

224
class GitlabAuthenticationError(GitlabError): ...
225
class GitlabHttpError(GitlabError): ...
226
class GitlabOperationError(GitlabError): ...
227
```
228

229
Common exception handling pattern:
230

231
```python
232
try:
233
    project = gl.projects.get(123)
234
except gitlab.GitlabGetError as e:
235
    print(f"Failed to get project: {e}")
236
except gitlab.GitlabAuthenticationError:
237
    print("Authentication failed")
238
```
239

240
## Configuration Management
241

242
```python { .api }
243
class GitlabConfigParser:
244
    def __init__(self, gitlab_id: str | None = None, config_files: list[str] | None = None) -> None: ...
245
    def get_gitlab_config(self, gitlab_id: str = "global") -> dict: ...
246
```
247

248
Configuration sources (in order of precedence):
249
1. Constructor parameters
250
2. Configuration files (`~/.python-gitlab.cfg`, `/etc/python-gitlab.cfg`)
251
3. Environment variables (`GITLAB_URL`, `GITLAB_PRIVATE_TOKEN`, etc.)
252

253
## Constants and Enums
254

255
```python { .api }
256
class AccessLevel(Enum):
257
    NO_ACCESS = 0
258
    MINIMAL_ACCESS = 5
259
    GUEST = 10
260
    PLANNER = 15
261
    REPORTER = 20
262
    DEVELOPER = 30
263
    MAINTAINER = 40
264
    OWNER = 50
265
    ADMIN = 60
266

267
class Visibility(Enum):
268
    PRIVATE = "private"
269
    INTERNAL = "internal"
270
    PUBLIC = "public"
271

272
# Access level constants
273
NO_ACCESS: int = 0
274
MINIMAL_ACCESS: int = 5
275
GUEST_ACCESS: int = 10
276
PLANNER_ACCESS: int = 15
277
REPORTER_ACCESS: int = 20
278
DEVELOPER_ACCESS: int = 30
279
MAINTAINER_ACCESS: int = 40
280
OWNER_ACCESS: int = 50
281
ADMIN_ACCESS: int = 60
282

283
DEFAULT_URL: str = "https://gitlab.com"
284
```
285

286
## Pagination
287

288
```python { .api }
289
class GitlabList:
290
    def __iter__(self) -> Iterator: ...
291
    def __len__(self) -> int: ...
292
    
293
    @property
294
    def current_page(self) -> int: ...
295
    @property
296
    def next_page(self) -> int | None: ...
297
    @property
298
    def per_page(self) -> int: ...
299
    @property
300
    def total(self) -> int | None: ...
301
    @property
302
    def total_pages(self) -> int | None: ...
303
```
304

305
Usage with automatic pagination:
306

307
```python
308
# Get all projects (automatically handles pagination)
309
projects = gl.projects.list(all=True)
310

311
# Manual pagination control
312
projects = gl.projects.list(page=1, per_page=20)
313
for project in projects:
314
    print(project.name)
315
    
316
# Check pagination info
317
print(f"Page {projects.current_page} of {projects.total_pages}")
318
```