Projects

Use Project objects to manipulate projects. The gitlab.Gitlab.projects manager objects provides helper functions.

Examples

List projects:

The API provides several filtering parameters for the listing methods:

  • archived: if True only archived projects will be returned
  • visibility: returns only projects with the specified visibility (can be public, internal or private)
  • search: returns project matching the given pattern

Results can also be sorted using the following parameters:

  • order_by: sort using the given argument. Valid values are id, name, path, created_at, updated_at and last_activity_at. The default is to sort by created_at
  • sort: sort order (asc or desc)
# Active projects
projects = gl.projects.list()
# Archived projects
projects = gl.projects.list(archived=1)
# Limit to projects with a defined visibility
projects = gl.projects.list(visibility='public')

# List owned projects
projects = gl.projects.owned()

# List starred projects
projects = gl.projects.starred()

# List all the projects
projects = gl.projects.all()

# Search projects
projects = gl.projects.list(search='keyword')

Get a single project:

# Get a project by ID
project = gl.projects.get(10)
# Get a project by userspace/name
project = gl.projects.get('myteam/myproject')

Create a project:

project = gl.projects.create({'name': 'project1'})

Create a project for a user (admin only):

alice = gl.users.list(username='alice')[0]
user_project = gl.user_projects.create({'name': 'project',
                                        'user_id': alice.id})

Create a project in a group:

You need to get the id of the group, then use the namespace_id attribute to create the group:

group_id = gl.groups.search('my-group')[0].id
project = gl.projects.create({'name': 'myrepo', 'namespace_id': group_id})

Update a project:

project.snippets_enabled = 1
project.save()

Delete a project:

gl.projects.delete(1)
# or
project.delete()

Fork a project:

fork = gl.project_forks.create({}, project_id=1)
# or
fork = project.forks.create({})

# fork to a specific namespace
fork = gl.project_forks.create({'namespace': 'myteam'}, project_id=1)

Create/delete a fork relation between projects (requires admin permissions):

project.create_fork_relation(source_project.id)
project.delete_fork_relation()

Star/unstar a project:

project.star()
project.unstar()

Archive/unarchive a project:

project.archive()
project.unarchive()

Note

Previous versions used archive_ and unarchive_ due to a naming issue, they have been deprecated but not yet removed.

Repository

The following examples show how you can manipulate the project code repository.

List the repository tree:

# list the content of the root directory for the default branch
items = project.repository_tree()

# list the content of a subdirectory on a specific branch
items = project.repository_tree(path='docs', ref='branch1')

Get the content of a file for a commit:

file_content = p.repository_blob('master', 'README.rst')

Get the repository archive:

# get the archive for the default branch
tgz = project.repository_archive()

# get the archive for a branch/tag/commit
tgz = project.repository_archive(sha='4567abc')

Warning

Archives are entirely stored in memory unless you use the streaming feature. See the artifacts example.

Get the content of a file using the blob id:

# find the id for the blob (simple search)
id = [d['id'] for d in p.repository_tree() if d['name'] == 'README.rst'][0]

# get the content
file_content = p.repository_raw_blob(id)

Warning

Blobs are entirely stored in memory unless you use the streaming feature. See the artifacts example.

Compare two branches, tags or commits:

result = project.repository_compare('master', 'branch1')

# get the commits
for i in commit:
    print(result.commits)

# get the diffs
for file_diff in commit.diffs:
    print(file_diff)

Get a list of contributors for the repository:

contributors = project.repository_contributors()

Files

The following examples show how you can manipulate the project files.

Get a file:

f = gl.project_files.get(file_path='README.rst', ref='master',
                         project_id=1)
# or
f = project.files.get(file_path='README.rst', ref='master')

# get the base64 encoded content
print(f.content)

# get the decoded content
print(f.decode())

Create a new file:

f = gl.project_files.create({'file_path': 'testfile',
                             'branch_name': 'master',
                             'content': file_content,
                             'commit_message': 'Create testfile'},
                            project_id=1)
# or
f = project.files.create({'file_path': 'testfile',
                          'branch_name': 'master',
                          'content': file_content,
                          'commit_message': 'Create testfile'})

Update a file. The entire content must be uploaded, as plain text or as base64 encoded text:

f.content = 'new content'
f.save(branch_name='master', commit_message='Update testfile')

# or for binary data
# Note: decode() is required with python 3 for data serialization. You can omit
# it with python 2
f.content = base64.b64encode(open('image.png').read()).decode()
f.save(branch_name='master', commit_message='Update testfile', encoding='base64')

Delete a file:

gl.project_files.delete({'file_path': 'testfile',
                         'branch_name': 'master',
                         'commit_message': 'Delete testfile'},
                        project_id=1)
# or
project.files.delete({'file_path': 'testfile',
                      'branch_name': 'master',
                      'commit_message': 'Delete testfile'})
# or
f.delete(commit_message='Delete testfile')

Tags

Use ProjectTag objects to manipulate tags. The gitlab.Gitlab.project_tags and Project.tags manager objects provide helper functions.

List the project tags:

tags = gl.project_tags.list(project_id=1)
# or
tags = project.tags.list()

Get a tag:

tag = gl.project_tags.list('1.0', project_id=1)
# or
tags = project.tags.list('1.0')

Create a tag:

tag = gl.project_tags.create({'tag_name': '1.0', 'ref': 'master'},
                             project_id=1)
# or
tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'})

Set or update the release note for a tag:

tag.set_release_description('awesome v1.0 release')

Delete a tag:

gl.project_tags.delete('1.0', project_id=1)
# or
project.tags.delete('1.0')
# or
tag.delete()

Snippets

Use ProjectSnippet objects to manipulate snippets. The gitlab.Gitlab.project_snippets and Project.snippets manager objects provide helper functions.

List the project snippets:

snippets = gl.project_snippets.list(project_id=1)
# or
snippets = project.snippets.list()

Get a snippet:

snippet = gl.project_snippets.list(snippet_id, project_id=1)
# or
snippets = project.snippets.list(snippet_id)

Get the content of a snippet:

print(snippet.content())

Warning

The snippet content is entirely stored in memory unless you use the streaming feature. See the artifacts example.

Create a snippet:

snippet = gl.project_snippets.create({'title': 'sample 1',
                                      'file_name': 'foo.py',
                                      'code': 'import gitlab',
                                      'visibility_level':
                                      gitlab.VISIBILITY_PRIVATE},
                                     project_id=1)
# or
snippet = project.snippets.create({'title': 'sample 1',
                                   'file_name': 'foo.py',
                                   'code': 'import gitlab',
                                   'visibility_level':
                                   gitlab.VISIBILITY_PRIVATE})

Update a snippet:

snippet.code = 'import gitlab\nimport whatever'
snippet.save

Delete a snippet:

gl.project_snippets.delete(snippet_id, project_id=1)
# or
project.snippets.delete(snippet_id)
# or
snippet.delete()

Notes

You can manipulate notes (comments) on the following resources:

  • ProjectIssue with ProjectIssueNote
  • ProjectMergeRequest with ProjectMergeRequestNote
  • ProjectSnippet with ProjectSnippetNote

List the notes for a resource:

i_notes = gl.project_issue_notes.list(project_id=1, issue_id=2)
mr_notes = gl.project_mergerequest_notes.list(project_id=1, merge_request_id=2)
s_notes = gl.project_snippet_notes.list(project_id=1, snippet_id=2)
# or
i_notes = issue.notes.list()
mr_notes = mr.notes.list()
s_notes = snippet.notes.list()

Get a note for a resource:

i_notes = gl.project_issue_notes.get(note_id, project_id=1, issue_id=2)
mr_notes = gl.project_mergerequest_notes.get(note_id, project_id=1,
                                             merge_request_id=2)
s_notes = gl.project_snippet_notes.get(note_id, project_id=1, snippet_id=2)
# or
i_note = issue.notes.get(note_id)
mr_note = mr.notes.get(note_id)
s_note = snippet.notes.get(note_id)

Create a note for a resource:

i_note = gl.project_issue_notes.create({'body': 'note content'},
                                       project_id=1, issue_id=2)
mr_note = gl.project_mergerequest_notes.create({'body': 'note content'}
                                               project_id=1,
                                               merge_request_id=2)
s_note = gl.project_snippet_notes.create({'body': 'note content'},
                                          project_id=1, snippet_id=2)
# or
i_note = issue.notes.create({'body': 'note content'})
mr_note = mr.notes.create({'body': 'note content'})
s_note = snippet.notes.create({'body': 'note content'})

Update a note for a resource:

note.body = 'updated note content'
note.save()

Delete a note for a resource:

note.delete()

Events

Use ProjectEvent objects to manipulate events. The gitlab.Gitlab.project_events and Project.events manager objects provide helper functions.

List the project events:

gl.project_events.list(project_id=1)
# or
project.events.list()

Team members

Use ProjectMember objects to manipulate projects members. The gitlab.Gitlab.project_members and Project.members manager objects provide helper functions.

List the project members:

members = gl.project_members.list()
# or
members = project.members.list()

Search project members matching a query string:

members = gl.project_members.list(query='foo')
# or
members = project.members.list(query='bar')

Get a single project member:

member = gl.project_members.get(1)
# or
member = project.members.get(1)

Add a project member:

member = gl.project_members.create({'user_id': user.id, 'access_level':
                                    gitlab.DEVELOPER_ACCESS},
                                   project_id=1)
# or
member = project.members.create({'user_id': user.id, 'access_level':
                                 gitlab.DEVELOPER_ACCESS})

Modify a project member (change the access level):

member.access_level = gitlab.MASTER_ACCESS
member.save()

Remove a member from the project team:

gl.project_members.delete(user.id, project_id=1)
# or
project.members.delete(user.id)
# or
member.delete()

Share the project with a group:

project.share(group.id, gitlab.DEVELOPER_ACCESS)

Hooks

Use ProjectHook objects to manipulate projects hooks. The gitlab.Gitlab.project_hooks and Project.hooks manager objects provide helper functions.

List the project hooks:

hooks = gl.project_hooks.list(project_id=1)
# or
hooks = project.hooks.list()

Get a project hook:

hook = gl.project_hooks.get(1, project_id=1)
# or
hook = project.hooks.get(1)

Create a project hook:

hook = gl.project_hooks.create({'url': 'http://my/action/url',
                                'push_events': 1},
                               project_id=1)
# or
hook = project.hooks.create({'url': 'http://my/action/url', 'push_events': 1})

Update a project hook:

hook.push_events = 0
hook.save()

Delete a project hook:

gl.project_hooks.delete(1, project_id=1)
# or
project.hooks.delete(1)
# or
hook.delete()

Pipelines

Use ProjectPipeline objects to manipulate projects pipelines. The gitlab.Gitlab.project_pipelines and Project.services manager objects provide helper functions.

List pipelines for a project:

pipelines = gl.project_pipelines.list(project_id=1)
# or
pipelines = project.pipelines.list()

Get a pipeline for a project:

pipeline = gl.project_pipelines.get(pipeline_id, project_id=1)
# or
pipeline = project.pipelines.get(pipeline_id)

Retry the failed builds for a pipeline:

pipeline.retry()

Cancel builds in a pipeline:

pipeline.cancel()

Create a pipeline for a particular reference:

pipeline = gl.project_pipelines.create({'project_id': 1, 'ref': 'master'})
# or
pipeline = project.pipelines.create({'ref': 'master'})

Services

Use ProjectService objects to manipulate projects services. The gitlab.Gitlab.project_services and Project.services manager objects provide helper functions.

Get a service:

service = gl.project_services.get(service_name='asana', project_id=1)
# or
service = project.services.get(service_name='asana', project_id=1)
# display it's status (enabled/disabled)
print(service.active)

List the code names of available services (doesn’t return objects):

services = gl.project_services.available()

Configure and enable a service:

service.api_key = 'randomkey'
service.save()

Disable a service:

service.delete()

Boards

Boards are a visual representation of existing issues for a project. Issues can be moved from one list to the other to track progress and help with priorities.

Get the list of existing boards for a project:

boards = gl.project_boards.list(project_id=1)
# or
boards = project.boards.list()

Get a single board for a project:

board = gl.project_boards.get(board_id, project_id=1)
# or
board = project.boards.get(board_id)

Boards have lists of issues. Each list is defined by a ProjectLabel and a position in the board.

List the issue lists for a board:

b_lists = board.lists.list()

Get a single list:

b_list = board.lists.get(list_id)

Create a new list. Note that getting the label ID is broken at the moment (see https://gitlab.com/gitlab-org/gitlab-ce/issues/23448):

# First get a ProjectLabel
label = get_or_create_label()
# Then use its ID to create the new board list
b_list = board.lists.create({'label_id': label.id})

Change a list position. The first list is at position 0. Moving a list will insert it at the given position and move the following lists up a position:

b_list.position = 2
b_list.save()

Delete a list:

b_list.delete()