Add info about the new location of Integrationsdocs/services-refactor

[ci skip]

19 files changed, 116 insertions, 77 deletions

diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md
index 51668128c62..cad4757f287 100644
--- a/doc/user/project/integrations/bamboo.md
+++ b/doc/user/project/integrations/bamboo.md
@@ -12,49 +12,48 @@ need to be configured in a Bamboo build plan before GitLab can integrate.
 
 ## Setup
 
-### Complete these steps in Bamboo:
+### Complete these steps in Bamboo
 
 1. Navigate to a Bamboo build plan and choose 'Configure plan' from the 'Actions'
-dropdown.
+   dropdown.
 1. Select the 'Triggers' tab.
 1. Click 'Add trigger'.
 1. Enter a description such as 'GitLab trigger'
 1. Choose 'Repository triggers the build when changes are committed'
 1. Check one or more repositories checkboxes
-1. Enter the GitLab IP address in the 'Trigger IP addresses' box. This is a 
-whitelist of IP addresses that are allowed to trigger Bamboo builds.
+1. Enter the GitLab IP address in the 'Trigger IP addresses' box. This is a
+   whitelist of IP addresses that are allowed to trigger Bamboo builds.
 1. Save the trigger.
-1. In the left pane, select a build stage. If you have multiple build stages 
-you want to select the last stage that contains the git checkout task.
+1. In the left pane, select a build stage. If you have multiple build stages
+   you want to select the last stage that contains the git checkout task.
 1. Select the 'Miscellaneous' tab.
-1. Under 'Pattern Match Labelling' put '${bamboo.repository.revision.number}' 
-in the 'Labels' box.
+1. Under 'Pattern Match Labelling' put '${bamboo.repository.revision.number}'
+   in the 'Labels' box.
 1. Save
 
 Bamboo is now ready to accept triggers from GitLab. Next, set up the Bamboo
-service in GitLab
+service in GitLab.
 
-### Complete these steps in GitLab:
+### Complete these steps in GitLab
 
 1. Navigate to the project you want to configure to trigger builds.
-1. Select 'Settings' in the top navigation.
-1. Select 'Services' in the left navigation.
+1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
 1. Click 'Atlassian Bamboo CI'
 1. Select the 'Active' checkbox.
 1. Enter the base URL of your Bamboo server. 'https://bamboo.example.com'
-1. Enter the build key from your Bamboo build plan. Build keys are a short, 
-all capital letter, identifier that is unique. It will be something like PR-BLD
-1. If necessary, enter username and password for a Bamboo user that has 
-access to trigger the build plan. Leave these fields blank if you do not require
-authentication.
+1. Enter the build key from your Bamboo build plan. Build keys are a short,
+   all capital letter, identifier that is unique. It will be something like PR-BLD
+1. If necessary, enter username and password for a Bamboo user that has
+   access to trigger the build plan. Leave these fields blank if you do not require
+   authentication.
 1. Save or optionally click 'Test Settings'. Please note that 'Test Settings'
-will actually trigger a build in Bamboo.
+   will actually trigger a build in Bamboo.
 
 ## Troubleshooting
 
 If builds are not triggered, these are a couple of things to keep in mind.
 
 1. Ensure you entered the right GitLab IP address in Bamboo under 'Trigger
-IP addresses'.
+   IP addresses'.
 1. Remember that GitLab only triggers builds on push events. A commit via the
-web interface will not trigger CI currently.
+   web interface will not trigger CI currently.
diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md
index 215ed6fe9cc..0b219e84478 100644
--- a/doc/user/project/integrations/bugzilla.md
+++ b/doc/user/project/integrations/bugzilla.md
@@ -1,7 +1,8 @@
 # Bugzilla Service
 
-Go to your project's **Settings > Services > Bugzilla** and fill in the required
-details as described in the table below.
+Navigate to the [Integrations page](project_services.md#accessing-the-project-services),
+select the **Bugzilla** service and fill in the required details as described
+in the table below.
 
 | Field | Description |
 | ----- | ----------- |
diff --git a/doc/user/project/integrations/builds_emails.md b/doc/user/project/integrations/builds_emails.md
index af0b1a287c7..f769dece242 100644
--- a/doc/user/project/integrations/builds_emails.md
+++ b/doc/user/project/integrations/builds_emails.md
@@ -1,7 +1,10 @@
-## Enabling build emails
+# Enabling build emails
 
-To receive e-mail notifications about the result status of your builds, visit
-your project's **Settings > Services > Builds emails** and activate the service.
+By enabling this service, you will be able to receive e-mail notifications about
+the result status of your builds.
+
+Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
+and select the **Builds emails** service to configure it.
 
 In the _Recipients_ area, provide a list of e-mails separated by comma.
 
@@ -10,7 +13,3 @@ e-mail notifications about each build's status.
 
 If you enable the _Notify only broken builds_ option, e-mail notifications will
 be sent only for failed builds.
-
----
-
-![Builds emails service settings](img/builds_emails_service.png)
diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md
index 2f9f36f962e..18109fc049c 100644
--- a/doc/user/project/integrations/emails_on_push.md
+++ b/doc/user/project/integrations/emails_on_push.md
@@ -1,7 +1,10 @@
-## Enabling emails on push
+# Enabling emails on push
 
-To receive email notifications for every change that is pushed to the project, visit
-your project's **Settings > Services > Emails on push** and activate the service.
+By enabling this service, you will be able to receive email notifications for
+every change that is pushed to your project.
+
+Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
+and select the **Emails on push** service to configure it.
 
 In the _Recipients_ area, provide a list of emails separated by commas.
 
diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md
index 021a93a288f..eee779c50d4 100644
--- a/doc/user/project/integrations/hipchat.md
+++ b/doc/user/project/integrations/hipchat.md
@@ -16,7 +16,7 @@ HipChat v2 API has tokens that are can be created using the Integrations tab
 in the Group or Room admin page. By design, these are lightweight tokens that
 allow GitLab to send messages only to *one* room.
 
-### Complete these steps in HipChat:
+### Complete these steps in HipChat
 
 1. Go to: https://admin.hipchat.com/admin
 1. Click on "Group Admin" -> "Integrations".
@@ -26,17 +26,16 @@ allow GitLab to send messages only to *one* room.
 see a URL in the format:
 
 ```
-    https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token>
+https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token>
 ```
 
 HipChat is now ready to accept messages from GitLab. Next, set up the HipChat
 service in GitLab.
 
-### Complete these steps in GitLab:
+### Complete these steps in GitLab
 
 1. Navigate to the project you want to configure for notifications.
-1. Select "Settings" in the top navigation.
-1. Select "Services" in the left navigation.
+1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
 1. Click "HipChat".
 1. Select the "Active" checkbox.
 1. Insert the `token` field from the URL into the `Token` field on the Web page.
diff --git a/doc/user/project/integrations/img/accessing_integrations.png b/doc/user/project/integrations/img/accessing_integrations.png
new file mode 100644
index 00000000000..3b941f64998
--- /dev/null
+++ b/doc/user/project/integrations/img/accessing_integrations.png
diff --git a/doc/user/project/integrations/img/builds_emails_service.png b/doc/user/project/integrations/img/builds_emails_service.png
deleted file mode 100644
index 9dbbed03833..00000000000
--- a/doc/user/project/integrations/img/builds_emails_service.png
+++ /dev/null
diff --git a/doc/user/project/integrations/img/project_services.png b/doc/user/project/integrations/img/project_services.png
new file mode 100644
index 00000000000..25b6cd5690b
--- /dev/null
+++ b/doc/user/project/integrations/img/project_services.png
diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md
index 766ffb1f65c..99093ebaed5 100644
--- a/doc/user/project/integrations/index.md
+++ b/doc/user/project/integrations/index.md
@@ -1,5 +1,11 @@
 # Project integrations
 
+You can find the available integrations under the **Integrations** page by
+navigating to the cog icon in the upper right corner of your project. You need
+to have at least [master permission][permissions] on the project.
+
+![Accessing the integrations](img/accessing_integrations.png)
+
 ## Project services
 
 Project services allow you to integrate GitLab with other applications.
@@ -8,7 +14,7 @@ adding functionality to GitLab.
 
 [Learn more about project services.](project_services.md)
 
-## Webhooks
+## Project webhooks
 
 Project webhooks allow you to trigger a URL if for example new code is pushed or
 a new issue is created. You can configure webhooks to listen for specific events
@@ -16,3 +22,5 @@ like pushes, issues or merge requests. GitLab will send a POST request with data
 to the webhook URL.
 
 [Learn more about webhooks.](webhooks.md)
+
+[permissions]: ../../permissions.md
diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md
index 25c0c3ad2a6..c63ea1316fe 100644
--- a/doc/user/project/integrations/irker.md
+++ b/doc/user/project/integrations/irker.md
@@ -23,11 +23,10 @@ from the GitLab service.
 If the Irker server runs on the same machine, you are done. If not, you will
 need to follow the firsts steps of the next section.
 
-## Complete these steps in GitLab:
+## Complete these steps in GitLab
 
 1. Navigate to the project you want to configure for notifications.
-1. Select "Settings" in the top navigation.
-1. Select "Services" in the left navigation.
+1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
 1. Click "Irker".
 1. Select the "Active" checkbox.
 1. Enter the server host address where `irkerd` runs (defaults to `localhost`)
diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md
index 233a2583c36..4c64d1e0907 100644
--- a/doc/user/project/integrations/jira.md
+++ b/doc/user/project/integrations/jira.md
@@ -90,8 +90,9 @@ password as they will be needed when configuring GitLab in the next section.
   the configuration options you have to enter. If you are using an older version,
   [follow this documentation][jira-repo-old-docs].
 
-To enable JIRA integration in a project, navigate to your project's
-**Services ➔ JIRA** and fill in the required details on the page as described
+To enable JIRA integration in a project, navigate to the
+[Integrations page](project_services.md#accessing-the-project-services), click
+the **JIRA** service, and fill in the required details on the page as described
 in the table below.
 
 | Field | Description |
diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md
index 7b33327f6cf..cc67e667472 100644
--- a/doc/user/project/integrations/kubernetes.md
+++ b/doc/user/project/integrations/kubernetes.md
@@ -12,6 +12,9 @@ template, see the [Services Templates](services_templates.md) document.
 
 ## Configuration
 
+Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
+of your project and select the **Kubernetes** service to configure it.
+
 ![Kubernetes configuration settings](img/kubernetes_configuration.png)
 
 The Kubernetes service takes the following arguments:
diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md
index fbc7dfeee6d..09ba9994d3a 100644
--- a/doc/user/project/integrations/mattermost.md
+++ b/doc/user/project/integrations/mattermost.md
@@ -18,8 +18,9 @@ Display name override is not enabled by default, you need to ask your admin to e
 
 After you set up Mattermost, it's time to set up GitLab.
 
-Go to your project's **Settings > Services > Mattermost Notifications** and you will see a
-checkbox with the following events that can be triggered:
+Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
+and select the **Mattermost notifications** service to configure it.
+There, you will see a checkbox with the following events that can be triggered:
 
 - Push
 - Issue
diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md
index 9a09e6d37ea..488f61c77a3 100644
--- a/doc/user/project/integrations/mattermost_slash_commands.md
+++ b/doc/user/project/integrations/mattermost_slash_commands.md
@@ -53,9 +53,11 @@ the administrator console.
 
 ### Step 2. Open the Mattermost slash commands service in GitLab
 
-1. Open a new tab for GitLab and go to your project's settings
-   **Services ➔ Mattermost command**. A screen will appear with all the values you
-   need to copy in Mattermost as described in the next step. Leave the window open.
+1. Open a new tab for GitLab, go to your project's
+   [Integrations page](project_services.md#accessing-the-project-services)
+   and select the **Mattermost command** service to configure it.
+   A screen will appear with all the values you need to copy in Mattermost as
+   described in the next step. Leave the window open.
 
     >**Note:**
     GitLab will propose some values for the Mattermost settings. The only one
diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md
index 547d855d777..a3a163a4c6b 100644
--- a/doc/user/project/integrations/project_services.md
+++ b/doc/user/project/integrations/project_services.md
@@ -1,28 +1,31 @@
-# Project Services
+# Project services
 
-Project services allow you to integrate GitLab with other applications. Below
-is list of the currently supported ones.
+Project services allow you to integrate GitLab with other applications. They
+are a bit like plugins in that they allow a lot of freedom in adding
+functionality to GitLab.
 
-You can find these within GitLab in the Services page under Project Settings if
-you are at least a master on the project.
-Project Services are a bit like plugins in that they allow a lot of freedom in
-adding functionality to GitLab. For example there is also a service that can
-send an email every time someone pushes new commits.
+## Accessing the project services
 
-Because GitLab is open source we can ship with the code and tests for all
-plugins. This allows the community to keep the plugins up to date so that they
-always work in newer GitLab versions.
+You can find the available services under the **Integrations** page in your
+project's settings.
 
-For an overview of what projects services are available without logging in,
-please see the [project_services directory][projects-code].
+1. Navigate to the cog icon in the upper right corner of your project. You need
+   to have at least [master permission][permissions] on the project.
 
-[projects-code]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/models/project_services
+    ![Accessing the services](img/accessing_integrations.png)
 
-Click on the service links to see
-further configuration instructions and details. Contributions are welcome.
+1. There are more than 20 services to integrate with. Click on the one that you
+   want to configure.
+
+    ![Project services list](img/project_services.png)
+
+Below, you will find a list of the currently supported ones accompanied with
+comprehensive documentation.
 
 ## Services
 
+Click on the service links to see further configuration instructions and details.
+
 | Service |	Description |
 | ------- | ----------- |
 | Asana     |	Asana - Teamwork without email |
@@ -51,9 +54,23 @@ further configuration instructions and details. Contributions are welcome.
 | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop |
 | [Redmine](redmine.md) | Redmine issue tracker |
 
-## Services Templates
+## Services templates
 
 Services templates is a way to set some predefined values in the Service of
 your liking which will then be pre-filled on each project's Service.
 
-Read more about [Services Templates in this document](services_templates.md).
+Read more about [Services templates in this document](services_templates.md).
+
+## Contributing to project services
+
+Because GitLab is open source we can ship with the code and tests for all
+plugins. This allows the community to keep the plugins up to date so that they
+always work in newer GitLab versions.
+
+For an overview of what projects services are available, please see the
+[project_services source directory][projects-code].
+
+Contributions are welcome!
+
+[projects-code]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/models/project_services
+[permissions]: ../../permissions.md
diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md
index b9830ea7c38..89c0312d3c2 100644
--- a/doc/user/project/integrations/redmine.md
+++ b/doc/user/project/integrations/redmine.md
@@ -1,7 +1,9 @@
 # Redmine Service
 
-Go to your project's **Settings > Services > Redmine** and fill in the required
-details as described in the table below.
+To enable the Redmine integration in a project, navigate to the
+[Integrations page](project_services.md#accessing-the-project-services), click
+the **Redmine** service, and fill in the required details on the page as described
+in the table below.
 
 | Field | Description |
 | ----- | ----------- |
diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md
index eaceb2be137..57a9492044b 100644
--- a/doc/user/project/integrations/slack.md
+++ b/doc/user/project/integrations/slack.md
@@ -15,8 +15,9 @@ Slack:
 
 After you set up Slack, it's time to set up GitLab.
 
-Go to your project's **Settings > Integrations > Slack Notifications** and you will see a
-checkbox with the following events that can be triggered:
+Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
+and select the **Slack notifications** service to configure it.
+There, you will see a checkbox with the following events that can be triggered:
 
 - Push
 - Issue
diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md
index 6efc2a168fa..56f1ba7311e 100644
--- a/doc/user/project/integrations/slack_slash_commands.md
+++ b/doc/user/project/integrations/slack_slash_commands.md
@@ -5,19 +5,20 @@
 Slack commands give users an extra interface to perform common operations
 from the chat environment. This allows one to, for example, create an issue as
 soon as the idea was discussed in chat.
-For all available commands try the help subcommand, for example: `/gitlab help`, 
+For all available commands try the help subcommand, for example: `/gitlab help`,
 all review the [full list of commands](../../../integration/chat_commands.md).
 
 ## Prerequisites
 
-A [team](https://get.slack.help/hc/en-us/articles/217608418-Creating-a-team) in Slack should be created beforehand, GitLab cannot create it for you.
+A [team](https://get.slack.help/hc/en-us/articles/217608418-Creating-a-team) in
+Slack should be created beforehand, GitLab cannot create it for you.
 
 ## Configuration
 
-First, navigate to the Slack Slash commands service page, found at your project's
-**Settings** > **Services**, and you find the instructions there:
+Go to your project's [Integrations page](project_services.md#accessing-the-project-services)
+and select the **Slack slash commands** service to configure it.
 
-   ![Slack setup instructions](img/slack_setup.png)
+![Slack setup instructions](img/slack_setup.png)
 
 Once you've followed the instructions, mark the service as active and insert the token
 you've received from Slack. After saving the service you are good to go!
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md
index 9d775355c4c..9df0c765f84 100644
--- a/doc/user/project/integrations/webhooks.md
+++ b/doc/user/project/integrations/webhooks.md
@@ -14,8 +14,11 @@ to the webhook URL.
 Webhooks can be used to update an external issue tracker, trigger CI builds,
 update a backup mirror, or even deploy to your production server.
 
-Navigate to the webhooks page by choosing **Webhooks** from your project's
-settings which can be found under the wheel icon in the upper right corner.
+Navigate to the webhooks page by going to the **Integrations** page from your
+project's settings which can be found under the wheel icon in the upper right
+corner.
+
+![Accessing the integrations](img/accessing_integrations.png)
 
 ## Webhook endpoint tips