Projects

Projects

Examples

List projects:

projects = gl.projects.list()

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)

# List all projects (default 20) projects = gl.projects.list(all=True) # 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.list(owned=True) # List starred projects projects = gl.projects.list(starred=True) # Search projects projects = gl.projects.list(search='keyword')

Get a single project:

# Get a project by ID project = gl.projects.get(project_id) # 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 = alice.projects.create({'name': 'project'}) user_projects = alice.projects.list()

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(project_id) # or project.delete()

Fork a project:

fork = project.forks.create({}) # fork to a specific namespace fork = project.forks.create({'namespace': 'myteam'})

Get a list of forks for the project:

forks = project.forks.list()

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

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

Get languages used in the project with percentage value:

languages = project.languages()

Star/unstar a project:

project.star() project.unstar()

Archive/unarchive a project:

project.archive() project.unarchive()

Start the housekeeping job:

project.housekeeping()

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 and metadata of a file for a commit, using a blob sha:

items = project.repository_tree(path='docs', ref='branch1') file_info = p.repository_blob(items[0]['id']) content = base64.b64decode(file_info['content']) size = file_info['size']

Get the repository archive:

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.

Get a snapshot of the repository:

tar_file = project.snapshot()

Warning

Snapshots 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 commit in result['commits']: print(commit) # get the diffs for file_diff in result['diffs']: print(file_diff)

Get a list of contributors for the repository:

contributors = project.repository_contributors()

Get a list of users for the repository:

users = p.users.list() # search for users users = p.users.list(search='pattern')

Start the pull mirroring process (EE edition):

project.mirror_pull()

Import / Export

You can export projects from gitlab, and re-import them to create new projects or overwrite existing ones.

Examples

A project export is an asynchronous operation. To retrieve the archive generated by GitLab you need to:

  1. Create an export using the API

  2. Wait for the export to be done

  3. Download the result

# Create the export p = gl.projects.get(my_project) export = p.exports.create({}) # Wait for the 'finished' status export.refresh() while export.export_status != 'finished': time.sleep(1) export.refresh() # Download the result with open('/tmp/export.tgz', 'wb') as f: export.download(streamed=True, action=f.write)

Import the project:

output = gl.projects.import_project(open('/tmp/export.tgz', 'rb'), 'my_new_project') # Get a ProjectImport object to track the import status project_import = gl.projects.get(output['id'], lazy=True).imports.get() while project_import.import_status != 'finished': time.sleep(1) project_import.refresh()

Project custom attributes

Examples

List custom attributes for a project:

attrs = project.customattributes.list()

Get a custom attribute for a project:

attr = project.customattributes.get(attr_key)

Set (create or update) a custom attribute for a project:

attr = project.customattributes.set(attr_key, attr_value)

Delete a custom attribute for a project:

attr.delete() # or project.customattributes.delete(attr_key)

Search projects by custom attribute:

project.customattributes.set('type', 'internal') gl.projects.list(custom_attributes={'type': 'internal'})

Project files

Examples

Get a file:

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 = project.files.create({'file_path': 'testfile.txt', 'branch': 'master', 'content': file_content, 'author_email': 'test@example.com', 'author_name': 'yourname', 'encoding': 'text', '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='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='master', commit_message='Update testfile', encoding='base64')

Delete a file:

f.delete(commit_message='Delete testfile')

Project tags

Examples

List the project tags:

tags = project.tags.list()

Get a tag:

tag = project.tags.get('1.0')

Create a tag:

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:

project.tags.delete('1.0') # or tag.delete()

Project snippets

The snippet visibility can be defined using the following constants:

  • gitlab.VISIBILITY_PRIVATE

  • gitlab.VISIBILITY_INTERNAL

  • gitlab.VISIBILITY_PUBLIC

Examples

List the project snippets:

snippets = project.snippets.list()

Get a snippet:

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 = 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:

project.snippets.delete(snippet_id) # or snippet.delete()

Get user agent detail (admin only):

detail = snippet.user_agent_detail()

Notes

See Notes.

Project members

Examples

List the project members:

members = project.members.list()

List the project members recursively (including inherited members through ancestor groups):

members = project.members.all(all=True)

Search project members matching a query string:

members = project.members.list(query='bar')

Get a single project member:

member = project.members.get(user_id)

Add a project member:

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.MAINTAINER_ACCESS member.save()

Remove a member from the project team:

project.members.delete(user.id) # or member.delete()

Share/unshare the project with a group:

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

Project hooks

Examples

List the project hooks:

hooks = project.hooks.list()

Get a project hook:

hook = project.hooks.get(hook_id)

Create a project hook:

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:

project.hooks.delete(hook_id) # or hook.delete()

Project Services

Examples

Get a service:

service = project.services.get('asana') # display its status (enabled/disabled) print(service.active)

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

services = project.services.available()

Configure and enable a service:

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

Disable a service:

service.delete()

File uploads

Examples

Upload a file into a project using a filesystem path:

project.upload("filename.txt", filepath="/some/path/filename.txt")

Upload a file into a project without a filesystem path:

project.upload("filename.txt", filedata="Raw data")

Upload a file and comment on an issue using the uploaded file’s markdown:

uploaded_file = project.upload("filename.txt", filedata="data") issue = project.issues.get(issue_id) issue.notes.create({ "body": "See the attached file: {}".format(uploaded_file["markdown"]) })

Upload a file and comment on an issue while using custom markdown to reference the uploaded file:

uploaded_file = project.upload("filename.txt", filedata="data") issue = project.issues.get(issue_id) issue.notes.create({ "body": "See the [attached file]({})".format(uploaded_file["url"]) })

Project push rules

Examples

Create project push rules (at least one rule is necessary):

project.pushrules.create({'deny_delete_tag': True})

Get project push rules (returns None is there are no push rules):

pr = project.pushrules.get()

Edit project push rules:

pr.branch_name_regex = '^(master|develop|support-\d+|release-\d+\..+|hotfix-.+|feature-.+)$' pr.save()

Delete project push rules:

pr.delete()

Project releases

Examples

Get a list of releases from a project:

release = project.releases.list()

Get a single release:

release = project.releases.get('v1.2.3')

Create a release for a project tag:

release = project.releases.create({'name':'Demo Release', 'tag_name':'v1.2.3', 'description':'release notes go here'})

Delete a release:

release = p.releases.delete('v1.2.3')

Project protected tags

Examples

Get a list of protected tags from a project:

protected_tags = project.protectedtags.list()

Get a single protected tag or wildcard protected tag:

protected_tag = project.protectedtags.get('v*')

Protect a single repository tag or several project repository tags using a wildcard protected tag:

project.protectedtags.create({'name': 'v*', 'create_access_level': '40'})

Unprotect the given protected tag or wildcard protected tag.:

protected_tag.delete()