Pass result data back from ansible
This loads a json file (work/results.json) that the job can write
to. It will be loaded by the executor after the job completes and
returned to the scheduler.
We can use the data in this file as the reported log URL for the
build. Later we can use it to supply file/line comments in
reviews.
Change-Id: Ib4eb743405f337c5bd541dd147e687fd44699713
diff --git a/doc/source/user/jobs.rst b/doc/source/user/jobs.rst
index 5637552..58f3371 100644
--- a/doc/source/user/jobs.rst
+++ b/doc/source/user/jobs.rst
@@ -101,3 +101,28 @@
.. TODO: describe standard lib and link to published docs for it.
+Return Values
+-------------
+
+The job may return some values to Zuul to affect its behavior. To
+return a value, use the *zuul_return* Ansible module in a job
+playbook. For example::
+
+ tasks:
+ - zuul_return:
+ data:
+ foo: bar
+
+Will return the dictionary "{'foo': 'bar'}" to Zuul.
+
+.. TODO: xref to section describing formatting
+
+Several uses of these values are planned, but the only currently
+implemented use is to set the log URL for a build. To do so, set the
+**zuul.log_url** value. For example::
+
+ tasks:
+ - zuul_return:
+ data:
+ zuul:
+ log_url: http://logs.example.com/path/to/build/logs