Add the possibility to pass the zuul url

This patch adds the zuul_url option in zuul conf file
in order to pass ZUUL_URL to Jenkins, which will be used
by devstack-vm-gate-wrap.sh.
Documentation added in launchers.rst and zuul.rst
explaining how this new option works.

Change-Id: I840423cc06fdfdacd301d30be3e0b3e589e563e9
diff --git a/doc/source/launchers.rst b/doc/source/launchers.rst
index 5e74bf6..c56d6e9 100644
--- a/doc/source/launchers.rst
+++ b/doc/source/launchers.rst
@@ -86,6 +86,10 @@
   The project that triggered this build
 **ZUUL_PIPELINE**
   The Zuul pipeline that is building this job
+**ZUUL_URL**
+  The url for the zuul server as configured in zuul.conf.  
+  A test runner may use this URL as the basis for fetching 
+  git commits.
 
 The following additional parameters will only be provided for builds
 associated with changes (i.e., in response to patchset-created or
diff --git a/doc/source/zuul.rst b/doc/source/zuul.rst
index 6b5d7c9..afe4cf6 100644
--- a/doc/source/zuul.rst
+++ b/doc/source/zuul.rst
@@ -139,6 +139,10 @@
   is included).  Defaults to ``false``.
   ``job_name_in_report=true``
 
+**zuul_url**
+  URL of Zuul's git repos, accessible to test workers.  
+  Usually "http://zuul.example.com/p".
+
 smtp
 """"
 
diff --git a/etc/zuul.conf-sample b/etc/zuul.conf-sample
index c193727..a4d1390 100644
--- a/etc/zuul.conf-sample
+++ b/etc/zuul.conf-sample
@@ -19,6 +19,7 @@
 ;git_user_email=zuul@example.com
 ;git_user_name=zuul
 status_url=https://jenkins.example.com/zuul/status
+zuul_url=http://zuul.example.com/p
 
 [smtp]
 server=localhost
diff --git a/tests/fixtures/zuul.conf b/tests/fixtures/zuul.conf
index 081258a..0cf27e1 100644
--- a/tests/fixtures/zuul.conf
+++ b/tests/fixtures/zuul.conf
@@ -14,6 +14,7 @@
 push_change_refs=true
 url_pattern=http://logs.example.com/{change.number}/{change.patchset}/{pipeline.name}/{job.name}/{build.number}
 job_name_in_report=true
+zuul_url=http://zuul.example.com/p
 
 [smtp]
 server=localhost
diff --git a/tests/test_scheduler.py b/tests/test_scheduler.py
old mode 100644
new mode 100755
index 385fda7..4832af9
--- a/tests/test_scheduler.py
+++ b/tests/test_scheduler.py
@@ -2408,6 +2408,24 @@
         self.assertEqual(D.reported, 2)
         self.assertEqual(len(self.history), 9)  # 3 each for A, B, D.
 
+    def test_zuul_url_return(self):
+        "Test if ZUUL_URL is returning when zuul_url is set in zuul.conf"
+        self.assertTrue(self.sched.config.has_option('zuul', 'zuul_url'))
+        self.worker.hold_jobs_in_build = True
+
+        A = self.fake_gerrit.addFakeChange('org/project', 'master', 'A')
+        A.addApproval('CRVW', 2)
+        self.fake_gerrit.addEvent(A.addApproval('APRV', 1))
+        self.waitUntilSettled()
+
+        self.assertEqual(len(self.builds), 1)
+        for build in self.builds:
+            self.assertTrue('ZUUL_URL' in build.parameters)
+
+        self.worker.hold_jobs_in_build = False
+        self.worker.release()
+        self.waitUntilSettled()
+
     def test_new_patchset_dequeues_old_on_head(self):
         "Test that a new patchset causes the old to be dequeued (at head)"
         # D -> C (depends on B) -> B (depends on A) -> A -> M
diff --git a/zuul/launcher/gearman.py b/zuul/launcher/gearman.py
index 2580397..d165f06 100644
--- a/zuul/launcher/gearman.py
+++ b/zuul/launcher/gearman.py
@@ -155,6 +155,8 @@
         self.sched = sched
         self.builds = {}
         self.meta_jobs = {}  # A list of meta-jobs like stop or describe
+        self.zuul_server = config.get('zuul', 'zuul_url')
+
         server = config.get('gearman', 'server')
         if config.has_option('gearman', 'port'):
             port = config.get('gearman', 'port')
@@ -224,6 +226,7 @@
         params = dict(ZUUL_UUID=uuid,
                       ZUUL_PROJECT=item.change.project.name)
         params['ZUUL_PIPELINE'] = pipeline.name
+        params['ZUUL_URL'] = self.zuul_server
         if hasattr(item.change, 'refspec'):
             changes_str = '^'.join(
                 ['%s:%s:%s' % (i.change.project.name, i.change.branch,