docs: updated docs for integrations, fixes #4137...
dan -
r552:9a0f45b0 default
Not Reviewed
Show More
Add another comment
TODOs: 0 unresolved 0 Resolved
COMMENTS: 0 General 0 Inline
@@ -0,0 +1,25
1 .. _extensions-hooks-ref:
2
3 Extensions & Hooks
4 ==================
5
6 The extensions & hooks section references three concepts regularly,
7 so to clarify what is meant each time, read the following definitions:
8
9 * **Plugin**: A Plugin is software that adds a specific feature to
10 an existing software application.
11 * **Extension**: An extension extends the capabilities of,
12 or the data available to, an existing software application.
13 * **Hook**: A hook intercepts function calls, messages, or events passed
14 between software components and can be used to trigger plugins, or their
15 extensions.
16
17 .. toctree::
18
19 rcx
20 install-ext
21 config-ext
22 extensions
23 hooks
24 full-blown-example
25 int-slack
@@ -0,0 +1,19
1 .. _integrations-hipchat:
2
3 Hipchat integration
4 ===================
5
6 In order to set a hipchat integration up it is necessary to obtain the Hipchat
7 service url by:
8
9 1. Login to Hipchat (https://www.hipchat.com/)
10 2. Goto `Integrations` -> `Build your own`
11 3. Select a room to post notifications to and save it
12
13 Once the integration is setup on hipchat you should have a url of the
14 form: `
15 which can be used in :ref:`creating-integrations`
16
17 Once you have set up a Hipchat webhook integrations url of the form:
18 ``https://yourapp.hipchat.com/v2/room/123456/notification?auth_token=...``,
19 create a ``hipchat`` integration in :ref:`creating-integrations`.
@@ -0,0 +1,26
1 .. _integrations-jira:
2
3 JIRA integration
4 ================
5
6 .. important::
7
8 In order to make issue numbers clickable in commit messages see the
9 :ref:`rhodecode-issue-trackers-ref` section. The JIRA integration
10 only deals with altering JIRA issues.
11
12 .. important::
13
14 JIRA integration is only available in |RCEE|.
15
16
17 The JIRA integration allows you to reference and change issue statuses in
18 JIRA directly from commit messages using commit message patterns such as
19 ``fixes #JIRA-235`` in order to change the status of issue JIRA-235 to
20 eg. ``Resolved``.
21
22 In order to apply a status to a JIRA issue it is necessary to find out the
23 transition status id which can be found in the Workflow section of JIRA.
24
25 Once you have the transition status id, create a ``jira`` integration in
26 :ref:`creating-integrations`.
@@ -0,0 +1,25
1 .. _integrations-redmine:
2
3 Redmine integration
4 ===================
5
6 .. important::
7
8 In order to make issue numbers clickable in commit messages see the
9 :ref:`rhodecode-issue-trackers-ref` section. The Redmine integration
10 only deals with altering Redmine issues.
11
12 .. important::
13
14 Redmine integration is only available in |RCEE|.
15
16 The Redmine integration allows you to reference and change issue statuses in
17 Redmine directly from commit messages using commit message patterns such as
18 ``fixes #235`` in order to change the status of issue 235 to eg. ``Resolved``
19
20 To set a Redmine integration up it is first necessary to obtain a Redmine api
21 key. This can be found in ``My Account`` in the Redmine application.
22 If it is not there, you may have to enable API Access in Redmine settings.
23
24 Once you have the api key, create a ``redmine`` integration in
25 :ref:`creating-integrations`.
@@ -0,0 +1,13
1 .. _integrations-slack:
2
3 Slack integration
4 =================
5
6 To set a Slack integration up it is first necessary to set up a Slack webhook api
7 endpoint for your slack channel, this can be done at:
8
9 https://my.slack.com/services/new/incoming-webhook/
10
11 Once you have set up a Slack webhook integrations url of the
12 form: ``https://hooks.slack.com/services/...``, create a ``slack`` integration
13 in :ref:`creating-integrations`.
@@ -0,0 +1,10
1 .. _integrations-webhook:
2
3 Webhook integration
4 ===================
5
6 The Webhook integration allows you to POST events such as repository pushes
7 or pull requests to a custom http endpoint as a json dict with details of the
8 event.
9
10 To create a webhook integration select ``webhook`` in :ref:`creating-integrations`.
@@ -121,7 +121,7
121 :ref:`indexing-ref` section for details.
121 :ref:`indexing-ref` section for details.
122 * To reconfigure any extensions, copy the backed up extensions into the
122 * To reconfigure any extensions, copy the backed up extensions into the
123 :file:`/home/{user}/.rccontrol/{instance-id}/rcextensions` and also specify
123 :file:`/home/{user}/.rccontrol/{instance-id}/rcextensions` and also specify
124 any custom hooks if necessary. See the :ref:`integrations-ref` section for
124 any custom hooks if necessary. See the :ref:`extensions-hooks-ref` section for
125 details.
125 details.
126
126
127 .. _Schrödinger's Backup: http://novabackup.novastor.com/blog/schrodingers-backup-good-bad-backup/
127 .. _Schrödinger's Backup: http://novabackup.novastor.com/blog/schrodingers-backup-good-bad-backup/
@@ -32,7 +32,7
32 -------------
32 -------------
33
33
34 To use the extra fields in an extension, see the example below. For more
34 To use the extra fields in an extension, see the example below. For more
35 information and examples, see the :ref:`integrations-ref` section.
35 information and examples, see the :ref:`extensions-hooks-ref` section.
36
36
37 .. code-block:: python
37 .. code-block:: python
38
38
@@ -14,7 +14,7
14
14
15 You can also use the |RCE| API set up continuous integration servers to leave
15 You can also use the |RCE| API set up continuous integration servers to leave
16 comments from a test suite. See the :ref:`api` and
16 comments from a test suite. See the :ref:`api` and
17 :ref:`integrations-ref` sections for examples on how to set this up.
17 :ref:`extensions-hooks-ref` sections for examples on how to set this up.
18
18
19 .. toctree::
19 .. toctree::
20
20
@@ -6,6 +6,8
6 .. |AE| replace:: Appenlight
6 .. |AE| replace:: Appenlight
7 .. |authtoken| replace:: Authentication Token
7 .. |authtoken| replace:: Authentication Token
8 .. |authtokens| replace:: **Auth Tokens**
8 .. |authtokens| replace:: **Auth Tokens**
9 .. |RCCEshort| replace:: Community
10 .. |RCEEshort| replace:: Enterprise
9 .. |git| replace:: Git
11 .. |git| replace:: Git
10 .. |hg| replace:: Mercurial
12 .. |hg| replace:: Mercurial
11 .. |svn| replace:: Subversion
13 .. |svn| replace:: Subversion
1 NO CONTENT: file renamed from docs/integrations/config-ext.rst to docs/extensions/config-ext.rst
NO CONTENT: file renamed from docs/integrations/config-ext.rst to docs/extensions/config-ext.rst
1 NO CONTENT: file renamed from docs/integrations/example-ext.py to docs/extensions/example-ext.py
NO CONTENT: file renamed from docs/integrations/example-ext.py to docs/extensions/example-ext.py
1 NO CONTENT: file renamed from docs/integrations/extensions.rst to docs/extensions/extensions.rst
NO CONTENT: file renamed from docs/integrations/extensions.rst to docs/extensions/extensions.rst
1 NO CONTENT: file renamed from docs/integrations/full-blown-example.rst to docs/extensions/full-blown-example.rst
NO CONTENT: file renamed from docs/integrations/full-blown-example.rst to docs/extensions/full-blown-example.rst
1 NO CONTENT: file renamed from docs/integrations/hooks.rst to docs/extensions/hooks.rst
NO CONTENT: file renamed from docs/integrations/hooks.rst to docs/extensions/hooks.rst
1 NO CONTENT: file renamed from docs/integrations/install-ext.rst to docs/extensions/install-ext.rst
NO CONTENT: file renamed from docs/integrations/install-ext.rst to docs/extensions/install-ext.rst
1 NO CONTENT: file renamed from docs/integrations/int-slack.rst to docs/extensions/int-slack.rst
NO CONTENT: file renamed from docs/integrations/int-slack.rst to docs/extensions/int-slack.rst
1 NO CONTENT: file renamed from docs/integrations/rcx.rst to docs/extensions/rcx.rst
NO CONTENT: file renamed from docs/integrations/rcx.rst to docs/extensions/rcx.rst
@@ -58,6 +58,7
58 collaboration/review-notifications
58 collaboration/review-notifications
59 collaboration/pull-requests
59 collaboration/pull-requests
60 code-review/code-review
60 code-review/code-review
61 integrations/integrations
61
62
62 .. toctree::
63 .. toctree::
63 :maxdepth: 1
64 :maxdepth: 1
@@ -65,7 +66,7
65
66
66 api/api
67 api/api
67 tools/rhodecode-tools
68 tools/rhodecode-tools
68 integrations/integrations
69 extensions/extensions-hooks
69 contributing/contributing
70 contributing/contributing
70
71
71 .. toctree::
72 .. toctree::
@@ -1,25 +1,49
1 .. _integrations-ref:
1 .. _integrations:
2
3 Integrations
4 ------------
2
5
3 Integrations and Extensions
6 Rhodecode supports integrations with external services for various events
4 ===========================
7 such as commit pushes and pull requests. Multiple integrations of the same type
8 (eg. slack) can be added at the same time which is useful for example to post
9 different events to different slack channels.
5
10
6 The integrations section references three concepts regularly,
11 Supported integrations
7 so to clarify what is meant each time, read the following definitions:
12 ^^^^^^^^^^^^^^^^^^^^^^
8
13
9 * **Plugin**: A Plugin is software that adds a specific feature to
14 ============================ ============ =====================================
10 an existing software application.
15 Type/Name |RC| Edition Description
11 * **Extension**: An extension extends the capabilities of,
16 ============================ ============ =====================================
12 or the data available to, an existing software application.
17 :ref:`integrations-slack` |RCCEshort| https://slack.com/
13 * **Hook**: A hook intercepts function calls, messages, or events passed
18 :ref:`integrations-hipchat` |RCCEshort| https://www.hipchat.com/
14 between software components and can be used to trigger plugins, or their
19 :ref:`integrations-webhook` |RCCEshort| POST events as `json` to a custom url
15 extensions.
20 :ref:`integrations-redmine` |RCEEshort| Close/Resolve/Reference redmine issues
21 :ref:`integrations-jira` |RCEEshort| Close/Resolve/Reference JIRA issues
22 ============================ ============ =====================================
23
24 .. _creating-integrations:
25
26 Creating an integration
27 ^^^^^^^^^^^^^^^^^^^^^^^
28
29 Integrations can be added globally via the admin UI:
30
31 :menuselection:`Admin --> Integrations`
32
33 or per repository in the repository settings:
34
35 :menuselection:`Admin --> Repositories --> Edit --> Integrations`
36
37 To create an integration, select the type from the list of types in the
38 `Create an integration` section.
39
40 The `Current integrations` section shows existing integrations that have been
41 created along with their type (eg. slack) and enabled status.
16
42
17 .. toctree::
43 .. toctree::
18
44
19 rcx
45 slack
20 install-ext
46 hipchat
21 config-ext
47 redmine
22 extensions
48 jira
23 hooks
49 webhook
24 full-blown-example
25 int-slack
@@ -301,7 +301,7
301
301
302 \ - -plugins
302 \ - -plugins
303 Add plugins to your |RCE| installation. See the
303 Add plugins to your |RCE| installation. See the
304 :ref:`integrations-ref` section for more details.
304 :ref:`extensions-hooks-ref` section for more details.
305
305
306 \ - -version
306 \ - -version
307 Display your |RCT| version.
307 Display your |RCT| version.
Comments 0
You need to be logged in to leave comments. Login now