Add documentation.
Change-Id: I8197ec2e52596fa4136f8af9aa93ea06e56d4d0d
diff --git a/doc/source/launchers.rst b/doc/source/launchers.rst
new file mode 100644
index 0000000..d936d4e
--- /dev/null
+++ b/doc/source/launchers.rst
@@ -0,0 +1,105 @@
+:title: Launchers
+
+Launchers
+=========
+
+Zuul has a modular architecture for launching jobs. Currently only
+Jenkins is supported, but it should be fairly easy to add a module to
+support other systems. Zuul makes very few assumptions about the
+interface to a launcher -- if it can trigger jobs, cancel them, and
+receive success or failure reports, it should be able to be used with
+Zuul. Patches to this effect are welcome.
+
+Jenkins
+-------
+
+Zuul works with Jenkins using the Jenkins API and the notification
+module. It uses the Jenkins API to trigger jobs, passing in
+parameters indicating what should be tested. It recieves
+notifications on job completion via the notification API (so jobs must
+be conifigured to notify Zuul).
+
+Jenkins Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+Zuul will need access to a Jenkins user. Create a user in Jenkins,
+and then visit the configuration page for the user:
+
+ https://jenkins.example.com/user/USERNAME/configure
+
+And click **Show API Token** to retrieve the API token for that user.
+You will need this later when configuring Zuul. Make sure that this
+user has appropriate permission to build any jobs that you want Zuul
+to trigger.
+
+Make sure the notification plugin is installed. Visit the plugin
+manager on your jenkins:
+
+ https://jenkins.example.com/pluginManager/
+
+And install **Jenkins Notification plugin**. The homepage for the
+plugin is at:
+
+ https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin
+
+Jenkins Job Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each job that you want Zuul to trigger, you will need to add a
+notification endpoint for the job on that job's configuration page.
+Click **Add Endpoint** and enter the following values:
+
+**Protocol**
+ ``HTTP``
+**URL**
+ ``http://127.0.0.1:8001/jenkins_endpoint``
+
+If you are running Zuul on a different server than Jenkins, enter the
+appropriate URL. Note that Zuul itself has no access controls, so
+ensure that only Jenkins is permitted to access that URL.
+
+Zuul will pass some parameters to Jenkins for every job it launches.
+Check **This build is parameterized**, and add the following fields
+with the type **String Parameter**:
+
+**UUID**
+ Zuul provided key to link builds with Gerrit events
+**GERRIT_PROJECT**
+ Zuul provided project name
+**GERRIT_BRANCH**
+ Zuul provided branch name
+**GERRIT_CHANGES**
+ Zuul provided list of dependent changes to merge
+
+You may find it useful to use the ``GERRIT_*`` variables in your job.
+In particular, ``GERRIT_CHANGES`` indicates the change or changes that
+should be tested. If Zuul has decided that more than one change
+should be merged and tested together, they will all be listed in
+``GERRIT_CHANGES``. The format for the description of one change is::
+
+ project:branch:refspec
+
+And multiple changes are separated by a carat ("^"). E.g.::
+
+ testproject:master:refs/changes/20/420/1^testproject:master:refs/changes/21/421/1"
+
+The OpenStack project uses the following script to update the
+repository in a workspace and merge appropriate changes:
+
+ https://github.com/openstack/openstack-ci-puppet/blob/master/modules/jenkins_slave/files/slave_scripts/gerrit-git-prep.sh
+
+Gerrit events that do not include a change (e.g., ref-updated events
+which are emitted after a git ref is updated (i.e., a commit is merged
+to master)) require a slightly different set of parameters:
+
+**UUID**
+ Zuul provided key to link builds with Gerrit events
+**GERRIT_PROJECT**
+ Zuul provided project name
+**GERRIT_REFNAME**
+ Zuul provided ref name
+**GERRIT_OLDREV**
+ Zuul provided old reference for ref-updated
+**GERRIT_NEWREV**
+ Zuul provided new reference for ref-updated
+