Add latest changes from gitlab-org/gitlab@master

1 files changed, 53 insertions, 41 deletions

diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md
index 295300fb55d..79df556ac8f 100644
--- a/doc/user/project/integrations/irker.md
+++ b/doc/user/project/integrations/irker.md
@@ -4,57 +4,69 @@ group: Ecosystem
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Irker IRC Gateway **(FREE)**
+# irker IRC Gateway **(FREE)**
 
-GitLab provides a way to push update messages to an Irker server. When
+GitLab provides a way to push update messages to an irker server. When
 configured, pushes to a project trigger the service to send data directly
-to the Irker server.
+to the irker server.
 
-See the [project homepage](https://gitlab.com/esr/irker) for further information.
+See also the [irker integration API documentation](../../../api/services.md).
 
-## Needed setup
+For more information, see the [irker project homepage](https://gitlab.com/esr/irker).
 
-You first need an Irker daemon. You can download the Irker code
-[from its repository](https://gitlab.com/esr/irker):
+## Set up an irker daemon
 
-```shell
-git clone https://gitlab.com/esr/irker.git
-```
+You need to set up an irker daemon. To do so:
 
-Once you have downloaded the code, you can run the Python script named `irkerd`.
-This script is the gateway script, it acts both as an IRC client, for sending
-messages to an IRC server, and as a TCP server, for receiving messages
-from the GitLab service.
+1. Download the irker code [from its repository](https://gitlab.com/esr/irker):
 
-If the Irker server runs on the same machine, you are done. If not, you
+   ```shell
+   git clone https://gitlab.com/esr/irker.git
+   ```
+
+1. Run the Python script named `irkerd`. This is the gateway script.
+   It acts both as an IRC client, for sending messages to an IRC server,
+   and as a TCP server, for receiving messages from the GitLab service.
+
+If the irker server runs on the same machine, you are done. If not, you
 need to follow the first steps of the next section.
 
+WARNING:
+irker does **not** have built-in authentication, which makes it vulnerable to spamming IRC channels if
+it is hosted outside of a firewall. To prevent abuse, make sure you run the daemon on a secured
+network. For more details, read
+[Security analysis of irker](http://www.catb.org/~esr/irker/security.html).
+
 ## Complete these steps in GitLab
 
-1. Navigate to the project you want to configure for notifications.
-1. Navigate to the [Integrations page](overview.md#accessing-integrations)
-1. Click "Irker".
+1. On the top bar, select **Menu > Projects** and find the project you want to
+   configure for notifications.
+1. Navigate to the [Integrations page](overview.md#accessing-integrations).
+1. Select **irker (IRC gateway)**.
 1. Ensure that the **Active** toggle is enabled.
-1. Enter the server host address where `irkerd` runs (defaults to `localhost`)
-   in the `Server host` field on the Web page
-1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the
-   `Server port` field on the Web page.
-1. Optional: if `Default IRC URI` is set, it has to be in the format
-   `irc[s]://domain.name` and is prepended to each and every channel provided
-   by the user which is not a full URI.
-1. Specify the recipients (e.g. #channel1, user1, etc.)
-1. Save or optionally click "Test Settings".
-
-## Note on Irker recipients
-
-Irker accepts channel names of the form `chan` and `#chan`, both for the
-`#chan` channel. If you want to send messages in query, you need to add
-`,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter
-case, `Aorimn` is treated as a nick and no more as a channel name.
-
-Irker can also join password-protected channels. Users need to append
-`?key=thesecretpassword` to the channel name. When using this feature remember to
-**not** put the `#` sign in front of the channel name; failing to do so
-results in Irker joining a channel literally named `#chan?key=password` henceforth
-leaking the channel key through the `/whois` IRC command (depending on IRC server
-configuration). This is due to a long standing Irker bug.
+1. Optional. Under **Server host**, enter the server host address where `irkerd` runs. If empty,
+   it defaults to `localhost`.
+1. Optional. Under **Server port**, enter the server port of `irkerd`. If empty, it defaults to `6659`.
+1. Optional. Under **Default IRC URI**, enter the default IRC URI, in the format `irc[s]://domain.name`.
+   It's prepended to every channel or user provided under **Recipients**, which is not a full URI.
+1. Under **Recipients**, enter the users or channels to receive updates, separated by spaces
+   (for example, `#channel1 user1`). For more details, see [Enter irker recipients](#enter-irker-recipients).
+1. Optional. Under **Colorize messages**, select the checkbox. irker will highlight your messages.
+1. Select **Save changes** or optionally select **Test Settings**.
+
+## Enter irker recipients
+
+If you left the **Default IRC URI** field empty, enter recipients as a full URI:
+`irc[s]://irc.network.net[:port]/#channel`. If you entered a default IRC URI there, you can use just
+channel or user names.
+
+To send messages:
+
+- To a channel (for example, `#chan`), irker accepts channel names of the form `chan` and
+  `#chan`.
+- To a password-protected channel, append `?key=thesecretpassword` to the channel name,
+  with the channel password instead of `thesecretpassword`. For example, `chan?key=hunter2`.
+  Do **not** put the `#` sign in front of the channel name. If you do, irker tries to join a
+  channel named `#chan?key=password` and so it can leak the channel password through the
+  `/whois` IRC command. This is due to a long-standing irker bug.
+- In a user query, add `,isnick` after the user name. For example, `UserSmith,isnick`.