docs: added CI integration docs.

docs/integrations/ci.rst

@@ -0,0 +1,97 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
+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}`
+    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
+
+
+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/index.rst

@@ -1,87 +1,87 b''
 |RCM|
 =====
 
 |RCM| is a high-performance source code management and collaboration system.
 It enables you to develop projects securely behind the firewall while
 providing collaboration tools that work with |git|, |hg|,
 and |svn| |repos|. The user interface allows you to create, edit,
 and commit files and |repos| while managing their security permissions.
 
 |RCM| provides the following features:
 
 * Source code management.
 * Extended permissions management.
 * Integrated code collaboration tools.
 * Integrated code review and notifications.
 * Scalability provided by multi-node setup.
 * Fully programmable automation API.
 * Web-based hook management.
 * Native |svn| support.
 * Migration from existing databases.
 * |RCM| SDK.
 * Built-in analytics
-* Built in integrations including: Slack, Jenkins, Webhooks, Jira, Redmine, Hipchat
+* Built in integrations including: Slack, Webhooks (used for Jenkins/TeamCity and other CIs), Jira, Redmine, Hipchat
 * Pluggable authentication system.
 * Support for AD, |LDAP|, Crowd, CAS, PAM.
 * Support for external authentication via Oauth Google, Github, Bitbucket, Twitter.
 * Debug modes of operation.
 * Private and public gists.
 * Gists with limited lifetimes and within instance only sharing.
 * Fully integrated code search function.
 * Always on SSL connectivity.
 
 .. only:: html
 
    Table of Contents
    -----------------
 
 .. toctree::
    :maxdepth: 1
    :caption: Admin Documentation
 
    install/quick-start
    install/install-database
    install/install-steps
    admin/system-overview
    nix/default-env
    admin/system-admin
    admin/user-admin
    admin/setting-repo-perms
    admin/security-tips
    auth/auth
    issue-trackers/issue-trackers
    admin/lab-settings
 
 .. toctree::
    :maxdepth: 1
    :caption: Feature Documentation
 
    collaboration/collaboration
    collaboration/review-notifications
    collaboration/pull-requests
    code-review/code-review
    integrations/integrations
 
 .. toctree::
    :maxdepth: 1
    :caption: Developer Documentation
 
    api/api
    tools/rhodecode-tools
    extensions/extensions-hooks
    contributing/contributing
 
 .. toctree::
    :maxdepth: 1
    :caption: User Documentation
 
    usage/basic-usage
    tutorials/tutorials
 
 .. toctree::
    :maxdepth: 1
    :caption: About
 
    known-issues/known-issues
    release-notes/release-notes
    admin/glossary

docs/integrations/integrations.rst

@@ -1,53 +1,54 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-email`       |RCEEshort|     Send repo push commits by email
+: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-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