Welcome to pyapi-gitlab’s documentation!

pyapi-gitlab is a wrapper to access all the functions of Gitlab from our python scripts.

How to use it

There are several optional parameters in a lot of the commands, you should check the command documentation or the command string, for example adding an user accepts up to 7 extra parameters.

First we import our library:

import gitlab

Then we need to authenticate to our Gitlab instance. There is 3 ways of doing this.

Authenticating via user/password

First create the instance passing the gitlab server as parameter:

git = gitlab.Gitlab("our_gitlab_host")

Then call the login() method:

git.login("user", "password")

That’s it, now your gitlab instance is using the private token in all the calls. You can see it in the token variable

Authenticating via private_token

You can also authenticate via the private_token that you can get from your gitlab profile and it’s easier than using user/password

Just call the instance with the parameter token:

git = gitlab.Gitlab("our_gitlab_host", token="mytoken")

Authenticating via oAuth2 token

You can also authenticate via the oAuth token that you can get from your gitlab profile and it’s easier than using user/password

Just call the instance with the parameter oauth_token:

git = gitlab.Gitlab("our_gitlab_host", oauth_token="mytoken")

Using sudo on the functions

All API calls support using sudo (e.g. calling the API as a different user) This is accomplished by using the setsudo() method to temporarily make all requests as another user, then calling it with no args to go back to the original user:

>>> git = gitlab.Gitlab(host=host)
>>> git.login(user=user, password=password)
True
>>> git.currentuser()["username"]
u'root'
>>> [[u["id"], u["username"]] for u in git.getusers()]
[[1, u'root'], [9, u'sudo_user'], [10, u'NMFUQ85Y']]
>>> # lets try with sudo_user
>>> git.setsudo(9)
>>> git.currentuser()["username"]
u'sudo_user'
>>> # lets change back to the original user
>>> git.setsudo(1)
>>> git.currentuser()["username"]
u'root'

Getting all results

There is a getall method which will return all results for any call that accepts pagination:

git.getall(git.getprojects)

Used in loops:

for project in git.getall(git.getprojects):
    pass

Treated as a generator:

print ", ".join(user['username'] for user in git.getall(git.getusers, per_page=100))

Wrap with list() which retrieves all the elements:

print 'number of users: %d' % len(list(git.getall(git.getusers)))

Start from any page:

# skip the first 4400 results
len(list(git.getall(git.getusers, page=51, per_page=80)))

And with positional args:

print len(list(git.getall(git.getgroupmembers, 191, page=3, per_page=7)))

API doc

Every method now has the documentation as a docstring. The best way of checking what the API entails is to go to the Gitlab API page directly as this library is a 1:1 translation of it. http://doc.gitlab.com/ce/api/README.html

pyapi-gitlab, a gitlab python wrapper for the gitlab API by Itxaka Serrano Garcia <itxakaserrano@gmail.com> Check the license on the LICENSE file

class gitlab.Gitlab(host, token='', oauth_token='', verify_ssl=True)

Gitlab class

acceptmergerequest(project_id, mergerequest_id, merge_commit_message=None)

Update an existing merge request.

Parameters:
  • project_id – ID of the project originating the merge request
  • mergerequest_id – ID of the merge request to accept
  • merge_commit_message – Custom merge commit message
Returns:

dict of the modified merge request
addcommenttomergerequest(project_id, mergerequest_id, note)

Add a comment to a merge request.

Parameters:
  • project_id – ID of the project originating the merge request
  • mergerequest_id – ID of the merge request to comment on
  • note – Text of comment
Returns:

True if success
adddeploykey(project_id, title, key)

Creates a new deploy key for a project.

Parameters:
  • project_id – project id
  • title – title of the key
  • key – the key itself
Returns:

true if sucess, false if not
addgroupmember(group_id, user_id, access_level)

Adds a project member to a project

Parameters:
  • user_id – user id
  • access_level – access level, see gitlab help to know more
Returns:

True if success
addprojecthook(project_id, url, push=False, issues=False, merge_requests=False, tag_push=False)

add a hook to a project :param id_: project id :param url: url of the hook :return: True if success

addprojectmember(project_id, user_id, access_level)

Adds a project member to a project

Parameters:
  • project_id – project id
  • user_id – user id
  • access_level – access level, see gitlab help to know more
Returns:

True if success
addsshkey(title, key)

Add a new ssh key for the current user

Parameters:
  • title – title of the new key
  • key – the key itself
Returns:

true if added, false if it didn’t add it (it could be because the name or key already exists)
addsshkeyuser(user_id, title, key)

Add a new ssh key for the user identified by id

Parameters:
  • user_id – id of the user to add the key to
  • title – title of the new key
  • key – the key itself
Returns:

true if added, false if it didn’t add it (it could be because the name or key already exists)
addsystemhook(url)

Add a system hook

Parameters:url – url of the hook
Returns:True if success
compare_branches_tags_commits(project_id, from_id, to_id)

Compare branches, tags or commits

Parameters:
  • project_id – The ID of a project
  • from_id – the commit sha or branch name
  • to_id – the commit sha or branch name
Returns:

commit list and diff between two branches tags or commits provided by name
createbranch(project_id, branch, ref)

Create branch from commit SHA or existing branch

Parameters:
  • project_id – The ID of a project
  • branch – The name of the branch
  • ref – Create branch from commit SHA or existing branch
Returns:

True if success, False if not
createfile(project_id, file_path, branch_name, content, commit_message)

Creates a new file in the repository

Parameters:
  • project_id – project id
  • file_path – Full path to new file. Ex. lib/class.rb
  • branch_name – The name of branch
  • content – File content
  • commit_message – Commit message
Returns:

true if success, false if not
createfork(project_id)

Forks a project into the user namespace of the authenticated user.

Parameters:project_id – Project ID to fork
Returns:True if succeed
createforkrelation(project_id, from_project_id)

Create a fork relation. This DO NOT create a fork but only adds a link as fork the relation between 2 repositories

Parameters:
  • project_id – project id
  • from_project_id – from id
Returns:

true if success
creategroup(name, path, **kwargs)

Creates a new group

Parameters:
  • name – The name of the group
  • path – The path for the group
  • kwargs – Any param the the Gitlab API supports
Returns:

dict of the new group
createissue(project_id, title, **kwargs)

Create a new issue

Parameters:
  • project_id – project id
  • title – title of the issue
Returns:

dict with the issue created
createissuewallnote(project_id, issue_id, content)

Create a new note

createlabel(project_id, name, color)

Creates a new label for given repository with given name and color.

Parameters:
  • project_id – The ID of a project
  • name – The name of the label
  • color – Color of the label given in 6-digit hex notation with leading ‘#’ sign (e.g. #FFAABB)
Returns:
createmergerequest(project_id, sourcebranch, targetbranch, title, target_project_id=None, assignee_id=None)

Create a new merge request.

Parameters:
  • project_id – ID of the project originating the merge request
  • sourcebranch – name of the branch to merge from
  • targetbranch – name of the branch to merge to
  • title – Title of the merge request
  • assignee_id – Assignee user ID
Returns:

dict of the new merge request
createmergerequestewallnote(project_id, merge_request_id, content)

Create a new note

createmilestone(project_id, title, **kwargs)

Create a new milestone

Parameters:
  • project_id – project id
  • title – title
  • description – description
  • due_date – due date
  • sudo – do the request as another user
Returns:

dict of the new issue
createproject(name, **kwargs)

Creates a new project owned by the authenticated user.

Parameters:
  • name – new project name
  • path – custom repository name for new project. By default generated based on name
  • namespace_id – namespace for the new project (defaults to user)
  • description – short project description
  • issues_enabled –
  • merge_requests_enabled –
  • wiki_enabled –
  • snippets_enabled –
  • public – if true same as setting visibility_level = 20
  • visibility_level –
  • sudo –
  • import_url –
Returns:
createprojectuser(user_id, name, **kwargs)

Creates a new project owned by the specified user. Available only for admins.

Parameters:
  • user_id – user_id of owner
  • name – new project name
  • description – short project description
  • default_branch – ‘master’ by default
  • issues_enabled –
  • merge_requests_enabled –
  • wiki_enabled –
  • snippets_enabled –
  • public – if true same as setting visibility_level = 20
  • visibility_level –
  • import_url –
  • sudo –
Returns:
createrepositorytag(project_id, tag_name, ref, message=None)

Creates new tag in the repository that points to the supplied ref

Parameters:
  • project_id – project id
  • tag_name – tag
  • ref – sha1 of the commit or branch to tag
  • message – message
Returns:

dict
createsnippet(project_id, title, file_name, code, lifetime='')

Creates an snippet

Parameters:
  • project_id – project id to create the snippet under
  • title – title of the snippet
  • file_name – filename for the snippet
  • code – content of the snippet
  • lifetime – expiration date
Returns:

True if correct, false if failed
createsnippetewallnote(project_id, snippet_id, content)

Create a new note

createuser(name, username, password, email, **kwargs)

Create a user

Parameters:
  • name – Obligatory
  • username – Obligatory
  • password – Obligatory
  • email – Obligatory
  • kwargs – Any param the the Gitlab API supports
Returns:

True if the user was created,false if it wasn’t(already exists)
currentuser()

Returns the current user parameters. The current user is linked to the secret token

Returns:a list with the current user properties
deletebranch(project_id, branch)

Delete branch by name

Parameters:
  • project_id – The ID of a project
  • branch – The name of the branch
Returns:

True if success, False if not
deletedeploykey(project_id, key_id)

Delete a deploy key from a project

Parameters:
  • project_id – project id
  • key_id – key id to delete
Returns:

true if success, false if not
deletefile(project_id, file_path, branch_name, commit_message)

Deletes existing file in the repository

Parameters:
  • project_id – project id
  • file_path – Full path to new file. Ex. lib/class.rb
  • branch_name – The name of branch
  • commit_message – Commit message
Returns:

true if success, false if not
deletegitlabciservice(project_id, token, project_url)

Delete GitLab CI service settings

Returns:true if success, false if not
deletegroup(group_id)

Deletes an group by ID

Parameters:group_id – id of the group to delete
Returns:True if it deleted, False if it couldn’t. False could happen for several reasons, but there isn’t a good way of differentiating them
deletegroupmember(group_id, user_id)

Delete a group member

Parameters:
  • group_id – group id to remove the member from
  • user_id – user id
Returns:

always true
deletelabel(project_id, name)

Deletes a label given by its name.

Parameters:
  • project_id – The ID of a project
  • name – The name of the label
Returns:

True if succeed
deleteproject(project_id)

Delete a project

Parameters:project_id – project id
Returns:always true
deleteprojecthook(project_id, hook_id)

Delete a project hook

Parameters:
  • project_id – project id
  • hook_id – hook id
Returns:

True if success
deleteprojectmember(project_id, user_id)

Delete a project member

Parameters:
  • project_id – project id
  • user_id – user id
Returns:

always true
deletesnippet(project_id, snippet_id)

Deletes a given snippet

Parameters:
  • project_id – project_id
  • snippet_id – snippet id
Returns:

True if success
deletesshkey(key_id)

Deletes an sshkey for the current user identified by id

Parameters:key_id – the id of the key
Returns:False if it didn’t delete it, True if it was deleted
deletesystemhook(hook_id)

Delete a project hook

Parameters:hook_id – hook id
Returns:True if success
deleteuser(user_id)

Deletes an user by ID

Parameters:user_id – id of the user to delete
Returns:True if it deleted, False if it couldn’t. False could happen for several reasons, but there isn’t a good way of differenting them
editgroupmember(group_id, user_id, access_level)

Edit user access level in a group

Parameters:
  • group_id – group id
  • user_id – user id
  • access_level – access level, see gitlab help to know more
Returns:

True if success
editissue(project_id, issue_id, **kwargs)

Edit an existing issue data

Parameters:
  • project_id – project id
  • issue_id – issue id
Returns:

true if success
editlabel(project_id, name, new_name=None, color=None)

Updates an existing label with new name or now color. At least one parameter is required, to update the label.

Parameters:
  • project_id – The ID of a project
  • name – The name of the label
Returns:

True if succeed
editmilestone(project_id, milestone_id, **kwargs)

Edit an existing milestone

Parameters:
  • project_id – project id
  • milestone_id – milestone id
  • title – title
  • description – description
  • due_date – due date
  • state_event – state
  • sudo – do the request as another user
Returns:

dict with the modified milestone
editproject(project_id, **kwargs)

Edit an existing project.

Parameters:
  • name – new project name
  • path – custom repository name for new project. By default generated based on name
  • default_branch – they default branch
  • description – short project description
  • issues_enabled –
  • merge_requests_enabled –
  • wiki_enabled –
  • snippets_enabled –
  • public – if true same as setting visibility_level = 20
  • visibility_level –
Returns:
editprojecthook(project_id, hook_id, url, push=False, issues=False, merge_requests=False, tag_push=False)

edit an existing hook from a project :param id_: project id :param hook_id: hook id :param url: the new url :return: True if success

editprojectmember(project_id, user_id, access_level)

Edit a project member

Parameters:
  • project_id – project id
  • user_id – user id
  • access_level – access level
Returns:

True if success
edituser(user_id, **kwargs)

Edits an user data.

Parameters:
  • user_id – id of the user to change
  • kwargs – Any param the the Gitlab API supports
Returns:

Dict of the user
static getall(fn, *args, **kwargs)

Auto-iterate over the paginated results of various methods of the API. Pass the GitLabAPI method as the first argument, followed by the other parameters as normal. Include page to determine first page to poll. Remaining kwargs are passed on to the called method, including per_page.

Parameters:
  • fn – Actual method to call
  • *args –

    Positional arguments to actual method

  • page – Optional, page number to start at, defaults to 1
  • **kwargs –

    Keyword arguments to actual method
Returns:

Yields each item in the result until exhausted, and then

implicit StopIteration; or no elements if error

getbranch(project_id, branch)

List one branch from a project

Parameters:
  • project_id – project id
  • branch – branch id
Returns:

the branch
getbranches(project_id)

List all the branches from a project

Parameters:project_id – project id
Returns:the branches
getcontributors(project_id, page=1, per_page=20)

Get repository contributors list

Param:project_id: The ID of a project
Returns:list of contributors
getdeploykey(project_id, key_id)

Get a single key.

Parameters:
  • project_id – project id
  • key_id – key id
Returns:

the key in a dict if success, false if not
getdeploykeys(project_id)

Get a list of a project’s deploy keys.

Parameters:project_id – project id
Returns:the keys in a dictionary if success, false if not
getfile(project_id, file_path, ref)

Allows you to receive information about file in repository like name, size, content. Note that file content is Base64 encoded.

Parameters:
  • project_id – project_id
  • file_path – Full path to file. Ex. lib/class.rb
  • ref – The name of branch, tag or commit
Returns:
getfilearchive(project_id, filepath='')

Get an archive of the repository

Parameters:
  • project_id – project id
  • filepath – path to save the file to
Returns:

True if the file was saved to the filepath
getgroupmembers(group_id, page=1, per_page=20)

Lists the members of a given group id

Parameters:
  • group_id – the group id
  • page – which page to return (default is 1)
  • per_page – number of items to return per page (default is 20)
Returns:

the group’s members
getgroups(group_id=None, page=1, per_page=20)

Retrieve group information

Parameters:group_id – Specify a group. Otherwise, all groups are returned
Returns:list of groups
getissues(page=1, per_page=20)

Return a global list of issues for your user.

Returns:list of issues
getissuewallnote(project_id, issue_id, note_id)

Get one note from the wall of the issue

getissuewallnotes(project_id, issue_id, page=1, per_page=20)

Get the notes from the wall of a issue

getlabels(project_id)

Get all labels for given project.

Parameters:project_id – The ID of a project
Returns:list of the labels
getmergerequest(project_id, mergerequest_id)

Get information about a specific merge request.

Parameters:
  • project_id – ID of the project
  • mergerequest_id – ID of the merge request
Returns:

dict of the merge request
getmergerequestchanges(project_id, mergerequest_id)

Get changes of a merge request.

Parameters:
  • project_id – ID of the project
  • mergerequest_id – ID of the merge request
Returns:

information about the merge request including files and changes
getmergerequestcomments(project_id, mergerequest_id, page=1, per_page=20)

Get comments of a merge request.

Parameters:
  • project_id – ID of the project
  • mergerequest_id – ID of the merge request
Returns:

list of the comments
getmergerequests(project_id, page=1, per_page=20, state=None)

Get all the merge requests for a project.

Parameters:
  • project_id – ID of the project to retrieve merge requests for
  • state – Passes merge request state to filter them by it
Returns:

list with all the merge requests
getmergerequestwallnote(project_id, merge_request_id, note_id)

Get one note from the wall of the merge request

getmergerequestwallnotes(project_id, merge_request_id, page=1, per_page=20)

Get the notes from the wall of a merge request

getmilestone(project_id, milestone_id)

Get an specific milestone

Parameters:
  • project_id – project id
  • milestone_id – milestone id
Returns:

dict with the new milestone
getmilestoneissues(project_id, milestone_id, page=1, per_page=20)

Get the issues associated with a milestone

Parameters:
  • project_id – project id
  • milestone_id – milestone id
Returns:

list of issues
getmilestones(project_id, page=1, per_page=20)

Get the milestones for a project

Parameters:project_id – project id
Returns:the milestones
getproject(project_id)

Get info for a project identified by id or namespace/project_name

Parameters:project_id – id or namespace/project_name of the project
Returns:False if not found, a dictionary if found
getprojectevents(project_id, page=1, per_page=20)

Get the project identified by id, events(commits)

Parameters:project_id – id of the project
Returns:False if no project with that id, a dictionary with the events if found
getprojecthook(project_id, hook_id)

Get a particular hook from a project

Parameters:
  • project_id – project id
  • hook_id – hook id
Returns:

the hook
getprojecthooks(project_id, page=1, per_page=20)

Get all the hooks from a project

Parameters:project_id – project id
Returns:the hooks
getprojectissue(project_id, issue_id)

Get an specific issue id from a project

Parameters:
  • project_id – project id
  • issue_id – issue id
Returns:

the issue
getprojectissues(project_id, page=1, per_page=20, **kwargs)

Return a list of issues for project id.

Param:project_id: The id for the project.
Returns:list of issues
getprojectmembers(project_id, query=None, page=1, per_page=20)

Lists the members of a given project id

Parameters:
  • project_id – the project id
  • query – Optional search query
  • page – Which page to return (default is 1)
  • per_page – Number of items to return per page (default is 20)
Returns:

the projects memebers, false if there is an error
getprojects(page=1, per_page=20)

Returns a dictionary of all the projects

Returns:list with the repo name, description, last activity,web url, ssh url, owner and if its public
getprojectsall(page=1, per_page=20)

Returns a dictionary of all the projects for admins only

Returns:list with the repo name, description, last activity,web url, ssh url, owner and if its public
getprojectsowned(page=1, per_page=20)

Returns a dictionary of all the projects for the current user

Returns:list with the repo name, description, last activity, web url, ssh url, owner and if its public
getrawblob(project_id, sha1)

Get the raw file contents for a blob by blob SHA.

Parameters:
  • project_id – The ID of a project
  • sha1 – the commit sha
Returns:

raw blob
getrawfile(project_id, sha1, filepath)

Get the raw file contents for a file by commit SHA and path.

Parameters:
  • project_id – The ID of a project
  • sha1 – The commit or branch name
  • filepath – The path the file
Returns:

raw file contents
getrepositories(project_id, page=1, per_page=20)

Gets all repositories for a project id

Parameters:project_id – project id
Returns:list of repos
getrepositorybranch(project_id, branch)

Get a single project repository branch.

Parameters:
  • project_id – project id
  • branch – branch
Returns:

dict of the branch
getrepositorycommit(project_id, sha1)

Get a specific commit identified by the commit hash or name of a branch or tag.

Parameters:
  • project_id – The ID of a project
  • sha1 – The commit hash or name of a repository branch or tag
Returns:

dic tof commit
getrepositorycommitdiff(project_id, sha1)

Get the diff of a commit in a project

Parameters:
  • project_id – The ID of a project
  • sha1 – The name of a repository branch or tag or if not given the default branch
Returns:

dict with the diff
getrepositorycommits(project_id, ref_name=None, page=1, per_page=20)

Get a list of repository commits in a project.

Parameters:
  • project_id – The ID of a project
  • ref_name – The name of a repository branch or tag or if not given the default branch
Returns:

list of commits
getrepositorytags(project_id, page=1, per_page=20)

Get a list of repository tags from a project, sorted by name in reverse alphabetical order.

Parameters:project_id – project id
Returns:list with all the tags
getrepositorytree(project_id, **kwargs)

Get a list of repository files and directories in a project.

Parameters:
  • project_id – The ID of a project
  • path – The path inside repository. Used to get contend of subdirectories
  • ref_name – The name of a repository branch or tag or if not given the default branch
Returns:

dcit with the tree
getsnippet(project_id, snippet_id)

Get one snippet from a project

Parameters:
  • project_id – project id to get the snippet from
  • snippet_id – snippet id
Returns:

dictionary
getsnippetcontent(project_id, snippet_id)

Get raw content of a given snippet

Parameters:
  • project_id – project_id for the snippet
  • snippet_id – snippet id
Returns:

the content of the snippet
getsnippets(project_id, page=1, per_page=20)

Get all the snippets of the project identified by project_id

Parameters:project_id – project id to get the snippets from
Returns:list of dictionaries
getsnippetwallnote(project_id, snippet_id, note_id)

Get one note from the wall of the snippet

getsnippetwallnotes(project_id, snippet_id, page=1, per_page=20)

Get the notes from the wall of a snippet

getsshkey(key_id)

Get a single ssh key identified by key_id

Parameters:key_id – the id of the key
Returns:the key itself
getsshkeys()

Gets all the ssh keys for the current user

Returns:a dictionary with the lists
getsystemhooks(page=1, per_page=20)

Get all system hooks

Returns:list of hooks
getuser(user_id)

Get info for a user identified by id

Parameters:user_id – id of the user
Returns:False if not found, a dictionary if found
getusers(search=None, page=1, per_page=20)

Return a user list

Parameters:
  • search – Optional search query
  • page – Which page to return (default is 1)
  • per_page – Number of items to return per page (default is 20)
Returns:

returs a dictionary of the users, false if there is an error
login(email=None, password=None, user=None)

Logs the user in and setups the header with the private token

Parameters:
  • user – gitlab user
  • password – gitlab password
Returns:

True if login successfull
moveproject(group_id, project_id)

Move a given project into a given group

Parameters:
  • group_id – ID of the destination group
  • project_id – ID of the project to be moved
Returns:

dict of the updated project
protectbranch(project_id, branch)

Protect a branch from changes

Parameters:
  • project_id – project id
  • branch – branch id
Returns:

True if success
protectrepositorybranch(project_id, branch)

Protects a single project repository branch. This is an idempotent function, protecting an already protected repository branch still returns a 200 OK status code.

Parameters:
  • project_id – project id
  • branch – branch to protech
Returns:

dict with the branch
removeforkrelation(project_id)

Remove an existing fork relation. this DO NOT remove the fork,only the relation between them

Parameters:project_id – project id
Returns:true if success
searchproject(search, page=1, per_page=20)

Search for projects by name which are accessible to the authenticated user

Parameters:search – query to search for
Returns:list of results
setgitlabciservice(project_id, token, project_url)

Set GitLab CI service for project

Parameters:
  • project_id – project id
  • token – CI project token
  • project_url – CI project url
Returns:

true if success, false if not
setsudo(user=None)

Set the subsequent API calls to the user provided

Parameters:user – User id or username to change to, None to return to the logged user
Returns:Nothing
testsystemhook(hook_id)

Test a system hook

Parameters:hook_id – hook id
Returns:list of hooks
unprotectbranch(project_id, branch)

Stop protecting a branch

Parameters:
  • project_id – project id
  • branch – branch id
Returns:

true if success
unprotectrepositorybranch(project_id, branch)

Unprotects a single project repository branch. This is an idempotent function, unprotecting an already unprotected repository branch still returns a 200 OK status code.

Parameters:
  • project_id – project id
  • branch – branch to unprotect
Returns:

dict with the branch
updatefile(project_id, file_path, branch_name, content, commit_message)

Updates an existing file in the repository

Parameters:
  • project_id – project id
  • file_path – Full path to new file. Ex. lib/class.rb
  • branch_name – The name of branch
  • content – File content
  • commit_message – Commit message
Returns:

true if success, false if not
updatemergerequest(project_id, mergerequest_id, **kwargs)

Update an existing merge request.

Parameters:
  • project_id – ID of the project originating the merge request
  • mergerequest_id – ID of the merge request to update
  • sourcebranch – name of the branch to merge from
  • targetbranch – name of the branch to merge to
  • title – Title of the merge request
  • assignee_id – Assignee user ID
  • closed – MR status. True = closed
Returns:

dict of the modified merge request

Indices and tables