Add support for triggering a new build

Fixes #184

3 files changed, 53 insertions, 11 deletions

diff --git a/docs/gl_objects/builds.py b/docs/gl_objects/builds.py
index 9f5ef12..911fc75 100644
--- a/docs/gl_objects/builds.py
+++ b/docs/gl_objects/builds.py
@@ -110,3 +110,9 @@ build.erase()
 # play
 build.play()
 # end play
+
+# trigger run
+p = gl.projects.get(project_id)
+p.trigger_build('master', trigger_token,
+                {'extra_var1': 'foo', 'extra_var2': 'bar'})
+# end trigger run
diff --git a/docs/gl_objects/builds.rst b/docs/gl_objects/builds.rst
index 78412b4..b20ca77 100644
--- a/docs/gl_objects/builds.rst
+++ b/docs/gl_objects/builds.rst
@@ -5,10 +5,12 @@ Builds
 Build triggers
 ==============
 
-Use :class:`~gitlab.objects.ProjectTrigger` objects to manipulate build
-triggers. The :attr:`gitlab.Gitlab.project_triggers` and
-:attr:`gitlab.objects.Project.triggers` manager objects provide helper
-functions.
+Build triggers provide a way to interact with the GitLab CI. Using a trigger a
+user or an application can run a new build for a specific commit.
+
+* Object class: :class:`~gitlab.objects.ProjectTrigger`
+* Manager objects: :attr:`gitlab.Gitlab.project_triggers`,
+  :attr:`Project.triggers <gitlab.objects.Project.triggers>`
 
 Examples
 --------
@@ -40,10 +42,11 @@ Remove a trigger:
 Build variables
 ===============
 
-Use :class:`~gitlab.objects.ProjectVariable` objects to manipulate build
-variables. The :attr:`gitlab.Gitlab.project_variables` and
-:attr:`gitlab.objects.Project.variables` manager objects provide helper
-functions.
+You can associate variables to builds to modify the build script behavior.
+
+* Object class: :class:`~gitlab.objects.ProjectVariable`
+* Manager objects: :attr:`gitlab.Gitlab.project_variables`,
+  :attr:`gitlab.objects.Project.variables`
 
 Examples
 --------
@@ -81,13 +84,25 @@ Remove a variable:
 Builds
 ======
 
-Use :class:`~gitlab.objects.ProjectBuild` objects to manipulate builds. The
-:attr:`gitlab.Gitlab.project_builds` and :attr:`gitlab.objects.Project.builds`
-manager objects provide helper functions.
+Builds are associated to projects and commits. They provide information on the
+build that have been run, and methods to manipulate those builds.
+
+* Object class: :class:`~gitlab.objects.ProjectBuild`
+* Manager objects: :attr:`gitlab.Gitlab.project_builds`,
+  :attr:`gitlab.objects.Project.builds`
 
 Examples
 --------
 
+Build are usually automatically triggered, but you can explicitly trigger a
+new build:
+
+Trigger a new build on a project:
+
+.. literalinclude:: builds.py
+   :start-after: # trigger run
+   :end-before: # end trigger run
+
 List builds for the project:
 
 .. literalinclude:: builds.py
diff --git a/gitlab/objects.py b/gitlab/objects.py
index b88934e..a9ca565 100644
--- a/gitlab/objects.py
+++ b/gitlab/objects.py
@@ -2386,6 +2386,27 @@ class Project(GitlabObject):
         r = self.gitlab._raw_post(url, data=data, **kwargs)
         raise_error_from_response(r, GitlabCreateError, 201)
 
+    def trigger_build(self, ref, token, variables={}, **kwargs):
+        """Trigger a CI build.
+
+        See https://gitlab.com/help/ci/triggers/README.md#trigger-a-build
+
+        Args:
+            ref (str): Commit to build; can be a commit SHA, a branch name, ...
+            token (str): The trigger token
+            variables (dict): Variables passed to the build script
+
+        Raises:
+            GitlabConnectionError: If the server cannot be reached.
+            GitlabCreateError: If the server fails to perform the request.
+        """
+        url = "/projects/%s/trigger/builds" % self.id
+        form = {r'variables[%s]' % k: v for k, v in six.iteritems(variables)}
+        data = {'ref': ref, 'token': token}
+        data.update(form)
+        r = self.gitlab._raw_post(url, data=data, **kwargs)
+        raise_error_from_response(r, GitlabCreateError, 201)
+
 
 class Runner(GitlabObject):
     _url = '/runners'