# HG changeset patch # User Daniel Dourvaris # Date 2016-08-04 02:14:57 # Node ID 9a0f45b0920a1ee4a5d1b887e02feefc113d2914 # Parent 86f5d1776584acb4a1a2c63823232d608be42d0b docs: updated docs for integrations, fixes #4137 * added docs for jira, hipchat, redmine, jira, webhook integrations * moved old integrations/rcextensions docs to "hooks & extensions" diff --git a/docs/admin/backup-restore.rst b/docs/admin/backup-restore.rst --- a/docs/admin/backup-restore.rst +++ b/docs/admin/backup-restore.rst @@ -121,7 +121,7 @@ then work on restoring any specific setu :ref:`indexing-ref` section for details. * To reconfigure any extensions, copy the backed up extensions into the :file:`/home/{user}/.rccontrol/{instance-id}/rcextensions` and also specify - any custom hooks if necessary. See the :ref:`integrations-ref` section for + any custom hooks if necessary. See the :ref:`extensions-hooks-ref` section for details. .. _Schrödinger's Backup: http://novabackup.novastor.com/blog/schrodingers-backup-good-bad-backup/ diff --git a/docs/admin/repo-extra-fields.rst b/docs/admin/repo-extra-fields.rst --- a/docs/admin/repo-extra-fields.rst +++ b/docs/admin/repo-extra-fields.rst @@ -32,7 +32,7 @@ Example Usage ------------- To use the extra fields in an extension, see the example below. For more -information and examples, see the :ref:`integrations-ref` section. +information and examples, see the :ref:`extensions-hooks-ref` section. .. code-block:: python diff --git a/docs/code-review/code-review.rst b/docs/code-review/code-review.rst --- a/docs/code-review/code-review.rst +++ b/docs/code-review/code-review.rst @@ -14,7 +14,7 @@ code review matters, see these posts on You can also use the |RCE| API set up continuous integration servers to leave comments from a test suite. See the :ref:`api` and -:ref:`integrations-ref` sections for examples on how to set this up. +:ref:`extensions-hooks-ref` sections for examples on how to set this up. .. toctree:: diff --git a/docs/common.py b/docs/common.py --- a/docs/common.py +++ b/docs/common.py @@ -6,6 +6,8 @@ rst_epilog = ''' .. |AE| replace:: Appenlight .. |authtoken| replace:: Authentication Token .. |authtokens| replace:: **Auth Tokens** +.. |RCCEshort| replace:: Community +.. |RCEEshort| replace:: Enterprise .. |git| replace:: Git .. |hg| replace:: Mercurial .. |svn| replace:: Subversion diff --git a/docs/integrations/config-ext.rst b/docs/extensions/config-ext.rst rename from docs/integrations/config-ext.rst rename to docs/extensions/config-ext.rst diff --git a/docs/integrations/example-ext.py b/docs/extensions/example-ext.py rename from docs/integrations/example-ext.py rename to docs/extensions/example-ext.py diff --git a/docs/extensions/extensions-hooks.rst b/docs/extensions/extensions-hooks.rst new file mode 100644 --- /dev/null +++ b/docs/extensions/extensions-hooks.rst @@ -0,0 +1,25 @@ +.. _extensions-hooks-ref: + +Extensions & Hooks +================== + +The extensions & hooks section references three concepts regularly, +so to clarify what is meant each time, read the following definitions: + +* **Plugin**: A Plugin is software that adds a specific feature to + an existing software application. +* **Extension**: An extension extends the capabilities of, + or the data available to, an existing software application. +* **Hook**: A hook intercepts function calls, messages, or events passed + between software components and can be used to trigger plugins, or their + extensions. + +.. toctree:: + + rcx + install-ext + config-ext + extensions + hooks + full-blown-example + int-slack diff --git a/docs/integrations/extensions.rst b/docs/extensions/extensions.rst rename from docs/integrations/extensions.rst rename to docs/extensions/extensions.rst diff --git a/docs/integrations/full-blown-example.rst b/docs/extensions/full-blown-example.rst rename from docs/integrations/full-blown-example.rst rename to docs/extensions/full-blown-example.rst diff --git a/docs/integrations/hooks.rst b/docs/extensions/hooks.rst rename from docs/integrations/hooks.rst rename to docs/extensions/hooks.rst diff --git a/docs/integrations/install-ext.rst b/docs/extensions/install-ext.rst rename from docs/integrations/install-ext.rst rename to docs/extensions/install-ext.rst diff --git a/docs/integrations/int-slack.rst b/docs/extensions/int-slack.rst rename from docs/integrations/int-slack.rst rename to docs/extensions/int-slack.rst diff --git a/docs/integrations/rcx.rst b/docs/extensions/rcx.rst rename from docs/integrations/rcx.rst rename to docs/extensions/rcx.rst diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -58,6 +58,7 @@ and commit files and |repos| while manag collaboration/review-notifications collaboration/pull-requests code-review/code-review + integrations/integrations .. toctree:: :maxdepth: 1 @@ -65,7 +66,7 @@ and commit files and |repos| while manag api/api tools/rhodecode-tools - integrations/integrations + extensions/extensions-hooks contributing/contributing .. toctree:: diff --git a/docs/integrations/hipchat.rst b/docs/integrations/hipchat.rst new file mode 100644 --- /dev/null +++ b/docs/integrations/hipchat.rst @@ -0,0 +1,19 @@ +.. _integrations-hipchat: + +Hipchat integration +=================== + +In order to set a hipchat integration up it is necessary to obtain the Hipchat +service url by: + +1. Login to Hipchat (https://www.hipchat.com/) +2. Goto `Integrations` -> `Build your own` +3. Select a room to post notifications to and save it + +Once the integration is setup on hipchat you should have a url of the +form: ` +which can be used in :ref:`creating-integrations` + +Once you have set up a Hipchat webhook integrations url of the form: +``https://yourapp.hipchat.com/v2/room/123456/notification?auth_token=...``, +create a ``hipchat`` integration in :ref:`creating-integrations`. diff --git a/docs/integrations/integrations.rst b/docs/integrations/integrations.rst --- a/docs/integrations/integrations.rst +++ b/docs/integrations/integrations.rst @@ -1,25 +1,49 @@ -.. _integrations-ref: +.. _integrations: + +Integrations +------------ -Integrations and Extensions -=========================== +Rhodecode supports integrations with external services for various events +such as commit pushes and pull requests. Multiple integrations of the same type +(eg. slack) can be added at the same time which is useful for example to post +different events to different slack channels. -The integrations section references three concepts regularly, -so to clarify what is meant each time, read the following definitions: +Supported integrations +^^^^^^^^^^^^^^^^^^^^^^ -* **Plugin**: A Plugin is software that adds a specific feature to - an existing software application. -* **Extension**: An extension extends the capabilities of, - or the data available to, an existing software application. -* **Hook**: A hook intercepts function calls, messages, or events passed - between software components and can be used to trigger plugins, or their - extensions. +============================ ============ ===================================== +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-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 the repository settings: + +:menuselection:`Admin --> Repositories --> Edit --> Integrations` + +To create an integration, select the type from the list of types in the +`Create an integration` section. + +The `Current integrations` section shows existing integrations that have been +created along with their type (eg. slack) and enabled status. .. toctree:: - rcx - install-ext - config-ext - extensions - hooks - full-blown-example - int-slack + slack + hipchat + redmine + jira + webhook diff --git a/docs/integrations/jira.rst b/docs/integrations/jira.rst new file mode 100644 --- /dev/null +++ b/docs/integrations/jira.rst @@ -0,0 +1,26 @@ +.. _integrations-jira: + +JIRA integration +================ + +.. important:: + + In order to make issue numbers clickable in commit messages see the + :ref:`rhodecode-issue-trackers-ref` section. The JIRA integration + only deals with altering JIRA issues. + +.. important:: + + JIRA integration is only available in |RCEE|. + + +The JIRA integration allows you to reference and change issue statuses in +JIRA directly from commit messages using commit message patterns such as +``fixes #JIRA-235`` in order to change the status of issue JIRA-235 to +eg. ``Resolved``. + +In order to apply a status to a JIRA issue it is necessary to find out the +transition status id which can be found in the Workflow section of JIRA. + +Once you have the transition status id, create a ``jira`` integration in +:ref:`creating-integrations`. diff --git a/docs/integrations/redmine.rst b/docs/integrations/redmine.rst new file mode 100644 --- /dev/null +++ b/docs/integrations/redmine.rst @@ -0,0 +1,25 @@ +.. _integrations-redmine: + +Redmine integration +=================== + +.. important:: + + In order to make issue numbers clickable in commit messages see the + :ref:`rhodecode-issue-trackers-ref` section. The Redmine integration + only deals with altering Redmine issues. + +.. important:: + + Redmine integration is only available in |RCEE|. + +The Redmine integration allows you to reference and change issue statuses in +Redmine directly from commit messages using commit message patterns such as +``fixes #235`` in order to change the status of issue 235 to eg. ``Resolved`` + +To set a Redmine integration up it is first necessary to obtain a Redmine api +key. This can be found in ``My Account`` in the Redmine application. +If it is not there, you may have to enable API Access in Redmine settings. + +Once you have the api key, create a ``redmine`` integration in +:ref:`creating-integrations`. diff --git a/docs/integrations/slack.rst b/docs/integrations/slack.rst new file mode 100644 --- /dev/null +++ b/docs/integrations/slack.rst @@ -0,0 +1,13 @@ +.. _integrations-slack: + +Slack integration +================= + +To set a Slack integration up it is first necessary to set up a Slack webhook api +endpoint for your slack channel, this can be done at: + +https://my.slack.com/services/new/incoming-webhook/ + +Once you have set up a Slack webhook integrations url of the +form: ``https://hooks.slack.com/services/...``, create a ``slack`` integration +in :ref:`creating-integrations`. diff --git a/docs/integrations/webhook.rst b/docs/integrations/webhook.rst new file mode 100644 --- /dev/null +++ b/docs/integrations/webhook.rst @@ -0,0 +1,10 @@ +.. _integrations-webhook: + +Webhook integration +=================== + +The Webhook integration allows you to POST events such as repository pushes +or pull requests to a custom http endpoint as a json dict with details of the +event. + +To create a webhook integration select ``webhook`` in :ref:`creating-integrations`. diff --git a/docs/tools/tools-cli.rst b/docs/tools/tools-cli.rst --- a/docs/tools/tools-cli.rst +++ b/docs/tools/tools-cli.rst @@ -301,7 +301,7 @@ used to send signals to build-bots such \ - -plugins Add plugins to your |RCE| installation. See the - :ref:`integrations-ref` section for more details. + :ref:`extensions-hooks-ref` section for more details. \ - -version Display your |RCT| version.