Merge branch 'docs/services-refactor' into 'master'

Add info about the new location of Integrations

Closes #27723

See merge request !9050

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.

doc/user/project/integrations/bugzilla.md

 # 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 |
 | ----- | ----------- |

doc/user/project/integrations/builds_emails.md

-## 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)

doc/user/project/integrations/emails_on_push.md

-## 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.
 

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.

doc/user/project/integrations/index.md

 # 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

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`)

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 |

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:

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

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

doc/user/project/integrations/project_services.md

-# 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

doc/user/project/integrations/redmine.md

 # 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 |
 | ----- | ----------- |

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

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!

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