diff options
| -rw-r--r-- | docs/gl_objects/builds.py | 6 | ||||
| -rw-r--r-- | docs/gl_objects/builds.rst | 37 | ||||
| -rw-r--r-- | gitlab/objects.py | 21 |
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' |