docs: updated docs about Jenkins CI integration.

docs/integrations/jenkins.rst

@@ -0,0 +1,113 b''
+.. _integrations-jenkins:
+
+Jenkins integration
+===================
+
+.. important::
+
+    Jenkins integration is only available in |RCEE|.
+
+
+
+Below are few examples how to use dedicated Jenkins integrations with |RCEE|.
+
+
+
+Configure Jenkins to check each commit after push
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to configure Jenkins to trigger a build on a project after each push we
+need to create a project that will allow triggering a build from external sources.
+
+In Jenkins, check `Trigger builds remotely (e.g., from scripts)` option. This gives
+now ability to trigger builds using an URL.
+
+.. image:: ../images/jenkins-build-with-parameters.png
+
+We also need to specify the parameters we're going to build the project with.
+In this example we'll use build with 3 parameters `COMMIT_ID`, `BRANCH_HEAD` and `BRANCH`.
+In Jenkins we need to add those 3 parameters, and check an option
+`This project is parameterised`
+
+.. image:: ../images/jenkins-adding-build-parameters.png
+
+
+Our final URL that |RCEE| Jenkins integration would use could look like this:
+
+This URL will be triggered for each pushed branch, and will include the branch head commit id.
+
+https://jenkins.server.com/job/test-build-commits/buildWithParameters?token=secret&BRANCH=${branch}&BRANCH_HEAD=${branch_head}
+
+Or we can also use commit_id in this case URL will be triggered for each pushed commit in the branch, and will include the commit id.
+
+https://jenkins.server.com/job/test-build-commits/buildWithParameters?token=secret&BRANCH=${branch}&COMMIT_ID=${commit_id}
+
+
+Now we have all the required information to fetch/checkout and test our project.
+We can write an example build common in Jenkins.
+
+
+.. image:: ../images/jenkins-build-command.png
+
+
+Below is an example of the integration page we used on |RCEE| side.
+
+
+.. image:: ../images/rhodecode-jenkins-integration-settings.png
+
+
+
+Configure Jenkins to check each pull-request on creation and updates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Jenkins integration also allows checking created pull-requests inside |RCCE|. This is
+somehow a special case compared to testing commits. The pull-requests cannot be cloned
+from the repository. Instead |RCCE| exposes different links back to CI systems which
+store information on how to obtain the pull-request code.
+
+On |RCCE| side we need to create a new integration that would use only two events:
+
+ - pullrequest created
+ - pullrequest commits updated
+
+This will trigger the builds when pull-request is firstly created, and then each time
+pull-requests is updated and commits that it stores change.
+
+
+In Jenkins, we should create at least two new build string parameters.
+We could use `PR_ID` and `SHADOW_URL`.
+Using those parameters, we can then create a customized build command to checkout a
+merged state of pull-request. And later on using rhodecode-api notify about the checks
+using the `PR_ID`.
+
+
+.. image:: ../images/jenkins-pr-build-command.png
+
+
+There's even a helper script we created to send notifications.
+Here's how the build on success could look like in Jenkins.
+
+.. code-block:: bash
+
+    # clone the ci-notify script, and save it into our $BUILD_TAG/notify directory
+    hg clone https://code.rhodecode.com/ci-notify $BUILD_TAG/notify
+
+    # execute the script. $RC_TOKEN is auth-token for API
+    # url is your rhodecode instance, repoid is repository project which PR was opened
+    # status could be "approved" or "rejected"
+    python $BUILD_TAG/notify/notify.py \
+        --token $RC_TOKEN \
+        --url https://code.server.com \
+        --repoid my-example-project \
+        --prid $PR_ID \
+        --status "approved" \
+        --message "Build Succeeded: $BUILD_URL"
+
+
+Below is also an example that we could use on |RCCE| side in the Jenkins integration settings.
+A Jenkins Trigger url that exposes all required information back to Jenkins CI server:
+
+.. code-block:: bash
+
+    http://jenkins.server.com/job/my-project-pull-request-tests/buildWithParameters?token=secret&PR_ID=${pull_request_id}&PR_TITLE=${pull_request_title}&SHADOW_URL=${pull_request_shadow_url}&PR_UID=${pull_request_commits_uid}
+

docs/integrations/ci.rst

@@ -1,97 +1,100 b''
 .. _integrations-ci:
 
 CI Server integration
 =====================
 
 
 RhodeCode :ref:`integrations-webhook` integration is a powerfull tool to allow
 interaction with systems like Jenkin, Bamboo, TeamCity, CircleCi or any other
 CI server that allows triggering a build using HTTP call.
 
 Below are few examples on how to use :ref:`integrations-webhook` to trigger
 a CI build.
 
 
 General Webhook
 +++++++++++++++
 
 :ref:`integrations-webhook` allows sending a JSON payload information to specified
-url with GET or POST methods. There are several variables that could be used
+custom URL with GET or POST methods. There are several variables that could be used
 in the URL greatly extending the flexibility of this type of integration.
 
 Most of the modern CI systems such as Jenkins, TeamCity, Bamboo or CircleCi
 allows triggering builds via GET or POST calls.
 
 :ref:`integrations-webhook` can be either specified per each repository or
 globally, if your CI maps directly to all your projects a global
 :ref:`integrations-webhook` integration can be created and will trigger builds
 for each change in projects. If only some projects allow triggering builds a
 global integration will also work because mostly a CI system will ignore a
 call for unspecified builds.
 
 
 .. note::
 
     A quick note on security. It's recommended to allow IP restrictions
     to only allow RhodeCode server to trigger builds. If you need to
     specify username and password this could be done by embedding it into a
     trigger URL, e.g. `http://user:[e-mail]/job/${project_id}`
 
 
 If users require to provide any custom parameters, they can be stored for each
 project inside the :ref:`repo-xtra`. For example to migrate a current job that
 has a numeric build id, storing this as `jenkins_build_id` key extra field
 the url would look like that::
 
     http://server/job/${extra:jenkins_build_id}/
 
 
 .. note::
 
     Please note that some variables will result in multiple calls.
     e.g. for |HG| specifying `${branch}` will trigger as many builds as how
-    many branches the suer actually pushed. Same applies to `${commit_id}`
+    many branches the user actually pushed. Same applies to `${commit_id}`
     This will trigger many builds if many commits are pushed. This allows
     triggering individual builds for each pushed commit.
 
 
 Jenkins
 +++++++
 
 To use Jenkins CI with RhodeCode, a Jenkins Build with Parameters should be used.
 Plugin details are available here: https://wiki.jenkins.io/display/JENKINS/Build+With+Parameters+Plugin
 
 If the plugin is configured, RhodeCode can trigger builds automatically by
 calling such example url provided in :ref:`integrations-webhook` integration::
 
     http://server/job/${project_id}/build-branch-${branch}/buildWithParameters?token=TOKEN&PARAMETER=value&PARAMETER2=value2
 
+The |RCEE| includes a custom :ref:`integrations-jenkins` integration. That allows using some
+of Jenkins added security features. Please check also the above link for more examples.
+
 
 Team City
 +++++++++
 
 To use TeamCity CI it's enough to call the API and provide a buildId.
 Example url after configuring :ref:`repo-xtra` would look like that::
 
     http://teacmtiyserver/viewType.html?buildTypeId=${extra:tc_build_id}
 
 
 Each project can have many build configurations.
 buildTypeId which is a unique ID for each build configuration (job).
 
 
 CircleCi
 ++++++++
 
 To use CircleCi, a POST call needs to be triggered. Example build url would
 look like this::
 
     http://cicleCiServer/project/${repo_type}/${username}/${repo_id}/tree/${branch}
 
 
 Circle Ci expects format of::
 
     POST: /project/:vcs-type/:username/:project/tree/:branch
 
 
 CircleCi API documentation can be found here: https://circleci.com/docs/api/v1-reference/

docs/integrations/integrations.rst

@@ -1,55 +1,57 b''
 .. _integrations:
 
 Integrations
 ------------
 
 Rhodecode supports integrations with external services for various events,
 such as commit pushes and pull requests. Multiple integrations of the same type
 can be added at the same time; this is useful for posting different events to
 different Slack channels, for example.
 
 Supported integrations
 ^^^^^^^^^^^^^^^^^^^^^^
 
 ============================    ============    =====================================
 Type/Name                       |RC| Edition    Description
 ============================    ============    =====================================
 :ref:`integrations-slack`       |RCCEshort|     https://slack.com/
 :ref:`integrations-hipchat`     |RCCEshort|     https://www.hipchat.com/
 :ref:`integrations-webhook`     |RCCEshort|     POST events as `json` to a custom url
 :ref:`integrations-ci`          |RCCEshort|     Trigger Builds for Common CI Systems
 :ref:`integrations-email`       |RCCEshort|     Send repo push commits by email
-:ref:`integrations-redmine`     |RCEEshort|     Close/Resolve/Reference redmine issues
+:ref:`integrations-jenkins`     |RCEEshort|     Trigger Builds for Jenkins CI System
+:ref:`integrations-redmine`     |RCEEshort|     Close/Resolve/Reference Redmine issues
 :ref:`integrations-jira`        |RCEEshort|     Close/Resolve/Reference JIRA issues
 ============================    ============    =====================================
 
 .. _creating-integrations:
 
 Creating an Integration
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Integrations can be added globally via the admin UI:
 
 :menuselection:`Admin --> Integrations`
 
 or per repository in each repository's settings:
 
 :menuselection:`Admin --> Repositories --> Edit --> Integrations`
 
 To create an integration, select the type from the list in the *Create New
 Integration* section.
 
 The *Current Integrations* section shows existing integrations that have been
 created along with their type (eg. Slack) and enabled status.
 
 See pages specific to each type of integration for more instructions:
 
 .. toctree::
 
    slack
    hipchat
    redmine
    jira
    webhook
    email
    ci
+   jenkins