diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -20,7 +20,7 @@ and commit files and |repos| while manag * 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. diff --git a/docs/integrations/ci.rst b/docs/integrations/ci.rst new file mode 100644 --- /dev/null +++ b/docs/integrations/ci.rst @@ -0,0 +1,97 @@ +.. _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:password@server.com/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/ diff --git a/docs/integrations/integrations.rst b/docs/integrations/integrations.rst --- a/docs/integrations/integrations.rst +++ b/docs/integrations/integrations.rst @@ -17,7 +17,8 @@ Type/Name |RC| Edi :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 ============================ ============ =====================================