projects.rst
1
########
2
Projects
3
########
4
5
Projects
6
========
7
8
Reference
9
---------
10
11
* v4 API:
12
13
+ :class:`gitlab.v4.objects.Project`
14
+ :class:`gitlab.v4.objects.ProjectManager`
15
+ :attr:`gitlab.Gitlab.projects`
16
17
* GitLab API: https://docs.gitlab.com/ce/api/projects.html
18
19
Examples
20
--------
22
List projects::
23
24
projects = gl.projects.list()
25
26
The API provides several filtering parameters for the listing methods:
27
28
* ``archived``: if ``True`` only archived projects will be returned
29
* ``visibility``: returns only projects with the specified visibility (can be
30
``public``, ``internal`` or ``private``)
31
* ``search``: returns project matching the given pattern
32
33
Results can also be sorted using the following parameters:
34
35
* ``order_by``: sort using the given argument. Valid values are ``id``,
36
``name``, ``path``, ``created_at``, ``updated_at`` and ``last_activity_at``.
37
The default is to sort by ``created_at``
38
* ``sort``: sort order (``asc`` or ``desc``)
39
42
# List all projects (default 20)
43
projects = gl.projects.list(all=True)
44
# Archived projects
45
projects = gl.projects.list(archived=1)
46
# Limit to projects with a defined visibility
47
projects = gl.projects.list(visibility='public')
49
# List owned projects
50
projects = gl.projects.list(owned=True)
52
# List starred projects
53
projects = gl.projects.list(starred=True)
55
# Search projects
56
projects = gl.projects.list(search='keyword')
58
.. note::
59
60
Fetching a list of projects, doesn't include all attributes of all projects.
61
To retrieve all attributes, you'll need to fetch a single project
62
63
Get a single project::
65
# Get a project by ID
66
project = gl.projects.get(project_id)
67
# Get a project by userspace/name
68
project = gl.projects.get('myteam/myproject')
70
Create a project::
72
project = gl.projects.create({'name': 'project1'})
74
Create a project for a user (admin only)::
76
alice = gl.users.list(username='alice')[0]
77
user_project = alice.projects.create({'name': 'project'})
78
user_projects = alice.projects.list()
80
Create a project in a group::
82
# You need to get the id of the group, then use the namespace_id attribute
83
# to create the group
84
group_id = gl.groups.search('my-group')[0].id
85
project = gl.projects.create({'name': 'myrepo', 'namespace_id': group_id})
87
Update a project::
89
project.snippets_enabled = 1
90
project.save()
92
Set the avatar image for a project::
93
94
# the avatar image can be passed as data (content of the file) or as a file
95
# object opened in binary mode
96
project.avatar = open('path/to/file.png', 'rb')
97
project.save()
98
99
Delete a project::
101
gl.projects.delete(project_id)
102
# or
103
project.delete()
104
105
Fork a project::
106
107
fork = project.forks.create({})
109
# fork to a specific namespace
110
fork = project.forks.create({'namespace': 'myteam'})
112
Get a list of forks for the project::
113
114
forks = project.forks.list()
115
116
Create/delete a fork relation between projects (requires admin permissions)::
118
project.create_fork_relation(source_project.id)
119
project.delete_fork_relation()
121
Get languages used in the project with percentage value::
122
123
languages = project.languages()
124
125
Star/unstar a project::
127
project.star()
128
project.unstar()
130
Archive/unarchive a project::
132
project.archive()
133
project.unarchive()
135
Start the housekeeping job::
137
project.housekeeping()
139
List the repository tree::
141
# list the content of the root directory for the default branch
142
items = project.repository_tree()
144
# list the content of a subdirectory on a specific branch
145
items = project.repository_tree(path='docs', ref='branch1')
147
Get the content and metadata of a file for a commit, using a blob sha::
149
items = project.repository_tree(path='docs', ref='branch1')
150
file_info = p.repository_blob(items[0]['id'])
151
content = base64.b64decode(file_info['content'])
152
size = file_info['size']
154
Update a project submodule::
155
156
items = project.update_submodule(
157
submodule="foo/bar",
158
branch="master",
159
commit_sha="4c3674f66071e30b3311dac9b9ccc90502a72664",
160
commit_message="Message", # optional
161
)
162
163
Get the repository archive::
165
tgz = project.repository_archive()
167
# get the archive for a branch/tag/commit
168
tgz = project.repository_archive(sha='4567abc')
169
170
.. warning::
171
172
Archives are entirely stored in memory unless you use the streaming feature.
173
See :ref:`the artifacts example <streaming_example>`.
174
175
Get the content of a file using the blob id::
177
# find the id for the blob (simple search)
178
id = [d['id'] for d in p.repository_tree() if d['name'] == 'README.rst'][0]
179
180
# get the content
181
file_content = p.repository_raw_blob(id)
182
183
.. warning::
184
185
Blobs are entirely stored in memory unless you use the streaming feature.
186
See :ref:`the artifacts example <streaming_example>`.
187
188
Get a snapshot of the repository::
189
190
tar_file = project.snapshot()
191
192
.. warning::
193
194
Snapshots are entirely stored in memory unless you use the streaming
195
feature. See :ref:`the artifacts example <streaming_example>`.
196
197
Compare two branches, tags or commits::
198
199
result = project.repository_compare('master', 'branch1')
201
# get the commits
202
for commit in result['commits']:
203
print(commit)
205
# get the diffs
206
for file_diff in result['diffs']:
207
print(file_diff)
209
Get a list of contributors for the repository::
211
contributors = project.repository_contributors()
213
Get a list of users for the repository::
214
215
users = p.users.list()
216
217
# search for users
218
users = p.users.list(search='pattern')
220
Start the pull mirroring process (EE edition)::
221
222
project.mirror_pull()
223
224
Import / Export
225
===============
226
227
You can export projects from gitlab, and re-import them to create new projects
228
or overwrite existing ones.
229
230
Reference
231
---------
232
233
* v4 API:
234
235
+ :class:`gitlab.v4.objects.ProjectExport`
236
+ :class:`gitlab.v4.objects.ProjectExportManager`
237
+ :attr:`gitlab.v4.objects.Project.exports`
238
+ :class:`gitlab.v4.objects.ProjectImport`
239
+ :class:`gitlab.v4.objects.ProjectImportManager`
240
+ :attr:`gitlab.v4.objects.Project.imports`
241
+ :attr:`gitlab.v4.objects.ProjectManager.import_project`
242
243
* GitLab API: https://docs.gitlab.com/ce/api/project_import_export.html
244
245
Examples
246
--------
247
248
A project export is an asynchronous operation. To retrieve the archive
249
generated by GitLab you need to:
250
251
#. Create an export using the API
252
#. Wait for the export to be done
253
#. Download the result
254
255
::
256
257
# Create the export
258
p = gl.projects.get(my_project)
259
export = p.exports.create({})
260
261
# Wait for the 'finished' status
262
export.refresh()
263
while export.export_status != 'finished':
264
time.sleep(1)
265
export.refresh()
266
267
# Download the result
268
with open('/tmp/export.tgz', 'wb') as f:
269
export.download(streamed=True, action=f.write)
270
271
Import the project::
272
273
output = gl.projects.import_project(open('/tmp/export.tgz', 'rb'), 'my_new_project')
274
# Get a ProjectImport object to track the import status
275
project_import = gl.projects.get(output['id'], lazy=True).imports.get()
276
while project_import.import_status != 'finished':
277
time.sleep(1)
278
project_import.refresh()
279
280
281
Project custom attributes
282
=========================
283
284
Reference
285
---------
286
287
* v4 API:
288
289
+ :class:`gitlab.v4.objects.ProjectCustomAttribute`
290
+ :class:`gitlab.v4.objects.ProjectCustomAttributeManager`
291
+ :attr:`gitlab.v4.objects.Project.customattributes`
292
293
* GitLab API: https://docs.gitlab.com/ce/api/custom_attributes.html
294
295
Examples
296
--------
297
298
List custom attributes for a project::
299
300
attrs = project.customattributes.list()
301
302
Get a custom attribute for a project::
303
304
attr = project.customattributes.get(attr_key)
305
306
Set (create or update) a custom attribute for a project::
307
308
attr = project.customattributes.set(attr_key, attr_value)
309
310
Delete a custom attribute for a project::
311
312
attr.delete()
313
# or
314
project.customattributes.delete(attr_key)
315
316
Search projects by custom attribute::
317
318
project.customattributes.set('type', 'internal')
319
gl.projects.list(custom_attributes={'type': 'internal'})
320
321
Project files
322
=============
323
324
Reference
325
---------
326
327
* v4 API:
329
+ :class:`gitlab.v4.objects.ProjectFile`
330
+ :class:`gitlab.v4.objects.ProjectFileManager`
331
+ :attr:`gitlab.v4.objects.Project.files`
332
333
* GitLab API: https://docs.gitlab.com/ce/api/repository_files.html
334
335
Examples
336
--------
338
Get a file::
339
340
f = project.files.get(file_path='README.rst', ref='master')
342
# get the base64 encoded content
343
print(f.content)
345
# get the decoded content
346
print(f.decode())
348
Create a new file::
349
350
f = project.files.create({'file_path': 'testfile.txt',
351
'branch': 'master',
352
'content': file_content,
353
'author_email': 'test@example.com',
354
'author_name': 'yourname',
355
'encoding': 'text',
356
'commit_message': 'Create testfile'})
357
358
Update a file. The entire content must be uploaded, as plain text or as base64
359
encoded text::
360
361
f.content = 'new content'
362
f.save(branch='master', commit_message='Update testfile')
364
# or for binary data
365
# Note: decode() is required with python 3 for data serialization. You can omit
366
# it with python 2
367
f.content = base64.b64encode(open('image.png').read()).decode()
368
f.save(branch='master', commit_message='Update testfile', encoding='base64')
370
Delete a file::
372
f.delete(commit_message='Delete testfile')
374
Get file blame::
375
376
b = project.files.blame(file_path='README.rst', ref='master')
377
378
Project tags
379
============
380
381
Reference
382
---------
383
384
* v4 API:
385
386
+ :class:`gitlab.v4.objects.ProjectTag`
387
+ :class:`gitlab.v4.objects.ProjectTagManager`
388
+ :attr:`gitlab.v4.objects.Project.tags`
389
390
* GitLab API: https://docs.gitlab.com/ce/api/tags.html
391
392
Examples
393
--------
395
List the project tags::
397
tags = project.tags.list()
399
Get a tag::
401
tag = project.tags.get('1.0')
403
Create a tag::
405
tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'})
407
Set or update the release note for a tag::
409
tag.set_release_description('awesome v1.0 release')
411
Delete a tag::
413
project.tags.delete('1.0')
414
# or
415
tag.delete()
417
.. _project_snippets:
418
419
Project snippets
420
================
422
The snippet visibility can be defined using the following constants:
423
424
* ``gitlab.VISIBILITY_PRIVATE``
425
* ``gitlab.VISIBILITY_INTERNAL``
426
* ``gitlab.VISIBILITY_PUBLIC``
427
428
Reference
429
---------
430
431
* v4 API:
432
433
+ :class:`gitlab.v4.objects.ProjectSnippet`
434
+ :class:`gitlab.v4.objects.ProjectSnippetManager`
435
+ :attr:`gitlab.v4.objects.Project.files`
436
437
* GitLab API: https://docs.gitlab.com/ce/api/project_snippets.html
438
439
Examples
440
--------
442
List the project snippets::
444
snippets = project.snippets.list()
446
Get a snippet::
448
snippets = project.snippets.list(snippet_id)
450
Get the content of a snippet::
452
print(snippet.content())
453
454
.. warning::
455
456
The snippet content is entirely stored in memory unless you use the
457
streaming feature. See :ref:`the artifacts example <streaming_example>`.
458
459
Create a snippet::
461
snippet = project.snippets.create({'title': 'sample 1',
462
'file_name': 'foo.py',
463
'code': 'import gitlab',
464
'visibility_level':
465
gitlab.VISIBILITY_PRIVATE})
467
Update a snippet::
469
snippet.code = 'import gitlab\nimport whatever'
470
snippet.save
472
Delete a snippet::
474
project.snippets.delete(snippet_id)
475
# or
476
snippet.delete()
478
Get user agent detail (admin only)::
479
480
detail = snippet.user_agent_detail()
481
482
Notes
485
See :ref:`project-notes`.
487
Project members
488
===============
490
Reference
491
---------
492
493
* v4 API:
494
495
+ :class:`gitlab.v4.objects.ProjectMember`
496
+ :class:`gitlab.v4.objects.ProjectMemberManager`
497
+ :attr:`gitlab.v4.objects.Project.members`
498
499
* GitLab API: https://docs.gitlab.com/ce/api/members.html
500
501
Examples
502
--------
504
List the project members::
506
members = project.members.list()
508
List the project members recursively (including inherited members through
509
ancestor groups)::
510
511
members = project.members.all(all=True)
512
513
Search project members matching a query string::
515
members = project.members.list(query='bar')
517
Get a single project member::
519
member = project.members.get(user_id)
521
Add a project member::
523
member = project.members.create({'user_id': user.id, 'access_level':
524
gitlab.DEVELOPER_ACCESS})
526
Modify a project member (change the access level)::
528
member.access_level = gitlab.MAINTAINER_ACCESS
529
member.save()
531
Remove a member from the project team::
533
project.members.delete(user.id)
534
# or
535
member.delete()
537
Share/unshare the project with a group::
539
project.share(group.id, gitlab.DEVELOPER_ACCESS)
540
project.unshare(group.id)
542
Project hooks
543
=============
544
545
Reference
546
---------
547
548
* v4 API:
549
550
+ :class:`gitlab.v4.objects.ProjectHook`
551
+ :class:`gitlab.v4.objects.ProjectHookManager`
552
+ :attr:`gitlab.v4.objects.Project.hooks`
553
554
* GitLab API: https://docs.gitlab.com/ce/api/projects.html#hooks
556
Examples
557
--------
559
List the project hooks::
561
hooks = project.hooks.list()
563
Get a project hook::
565
hook = project.hooks.get(hook_id)
567
Create a project hook::
569
hook = project.hooks.create({'url': 'http://my/action/url', 'push_events': 1})
571
Update a project hook::
573
hook.push_events = 0
574
hook.save()
576
Delete a project hook::
578
project.hooks.delete(hook_id)
579
# or
580
hook.delete()
582
Project Services
583
================
584
585
Reference
586
---------
587
588
* v4 API:
589
590
+ :class:`gitlab.v4.objects.ProjectService`
591
+ :class:`gitlab.v4.objects.ProjectServiceManager`
592
+ :attr:`gitlab.v4.objects.Project.services`
593
594
* GitLab API: https://docs.gitlab.com/ce/api/services.html
595
596
Examples
597
---------
599
Get a service::
601
service = project.services.get('asana')
602
# display its status (enabled/disabled)
603
print(service.active)
605
List the code names of available services (doesn't return objects)::
607
services = project.services.available()
609
Configure and enable a service::
611
service.api_key = 'randomkey'
612
service.save()
614
Disable a service::
616
service.delete()
618
File uploads
619
============
620
621
Reference
622
---------
623
624
* v4 API:
625
626
+ :attr:`gitlab.v4.objects.Project.upload`
627
628
* Gitlab API: https://docs.gitlab.com/ce/api/projects.html#upload-a-file
629
630
Examples
631
--------
632
633
Upload a file into a project using a filesystem path::
635
project.upload("filename.txt", filepath="/some/path/filename.txt")
637
Upload a file into a project without a filesystem path::
639
project.upload("filename.txt", filedata="Raw data")
640
641
Upload a file and comment on an issue using the uploaded file's
642
markdown::
644
uploaded_file = project.upload("filename.txt", filedata="data")
645
issue = project.issues.get(issue_id)
646
issue.notes.create({
647
"body": "See the attached file: {}".format(uploaded_file["markdown"])
648
})
649
650
Upload a file and comment on an issue while using custom
651
markdown to reference the uploaded file::
653
uploaded_file = project.upload("filename.txt", filedata="data")
654
issue = project.issues.get(issue_id)
655
issue.notes.create({
656
"body": "See the [attached file]({})".format(uploaded_file["url"])
657
})
658
659
Project push rules
660
==================
661
662
Reference
663
---------
664
665
* v4 API:
666
667
+ :class:`gitlab.v4.objects.ProjectPushRules`
668
+ :class:`gitlab.v4.objects.ProjectPushRulesManager`
669
+ :attr:`gitlab.v4.objects.Project.pushrules`
670
671
* GitLab API: https://docs.gitlab.com/ee/api/projects.html#push-rules
672
673
Examples
674
---------
675
676
Create project push rules (at least one rule is necessary)::
677
678
project.pushrules.create({'deny_delete_tag': True})
679
680
Get project push rules (returns None is there are no push rules)::
681
682
pr = project.pushrules.get()
683
684
Edit project push rules::
685
686
pr.branch_name_regex = '^(master|develop|support-\d+|release-\d+\..+|hotfix-.+|feature-.+)$'
687
pr.save()
688
689
Delete project push rules::
690
691
pr.delete()
693
Project releases
694
================
695
696
Reference
697
---------
698
699
* v4 API:
700
701
+ :class:`gitlab.v4.objects.ProjectRelease`
702
+ :class:`gitlab.v4.objects.ProjectReleaseManager`
703
+ :attr:`gitlab.v4.objects.Project.releases`
704
705
* Gitlab API: https://docs.gitlab.com/ee/api/releases/index.html
706
707
Examples
708
--------
709
710
Get a list of releases from a project::
711
712
release = project.releases.list()
713
714
Get a single release::
715
716
release = project.releases.get('v1.2.3')
717
718
Create a release for a project tag::
719
720
release = project.releases.create({'name':'Demo Release', 'tag_name':'v1.2.3', 'description':'release notes go here'})
721
722
Delete a release::
723
724
release = p.releases.delete('v1.2.3')
725
726
Project protected tags
727
======================
728
729
Reference
730
---------
731
732
* v4 API:
733
734
+ :class:`gitlab.v4.objects.ProjectProtectedTag`
735
+ :class:`gitlab.v4.objects.ProjectProtectedTagManager`
736
+ :attr:`gitlab.v4.objects.Project.protectedtags`
737
738
* GitLab API: https://docs.gitlab.com/ce/api/protected_tags.html
739
740
Examples
741
---------
742
743
Get a list of protected tags from a project::
744
745
protected_tags = project.protectedtags.list()
746
747
Get a single protected tag or wildcard protected tag::
748
749
protected_tag = project.protectedtags.get('v*')
750
751
Protect a single repository tag or several project repository tags using a wildcard protected tag::
752
753
project.protectedtags.create({'name': 'v*', 'create_access_level': '40'})
754
755
Unprotect the given protected tag or wildcard protected tag.::
756
757
protected_tag.delete()