Automatic merge of gitlab-org/gitlab-ce master

doc/api/broadcast_messages.md

 # Broadcast Messages API
 
-> **Note:** This feature was introduced in GitLab 8.12.
+> Introduced in GitLab 8.12.
 
-The broadcast message API is only accessible to administrators. All requests by
-guests will respond with `401 Unauthorized`, and all requests by normal users
-will respond with `403 Forbidden`.
+Broadcast messages API operates on [broadcast messages](../user/admin_area/broadcast_messages.md).
+
+The broadcast message API is only accessible to administrators. All requests by:
+
+- Guests will result in `401 Unauthorized`.
+- Regular users will result in `403 Forbidden`.
 
 ## Get all broadcast messages
 
-```
+List all broadcast messages.
+
+```text
 GET /broadcast_messages
 ```
 
-```bash
+Example request:
+
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
 ```
 
@@ -34,15 +41,21 @@ Example response:
 
 ## Get a specific broadcast message
 
-```
+Get a specific broadcast message.
+
+```text
 GET /broadcast_messages/:id
 ```
 
+Parameters:
+
 | Attribute | Type    | Required | Description                          |
-| ----------- | -------- | -------- | ------------------------- |
-| `id`        | integer  | yes      | Broadcast message ID      |
+|:----------|:--------|:---------|:-------------------------------------|
+| `id`      | integer | yes      | ID of broadcast message to retrieve. |
+
+Example request:
 
-```bash
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
 ```
 
@@ -62,19 +75,25 @@ Example response:
 
 ## Create a broadcast message
 
-```
+Create a new broadcast message.
+
+```text
 POST /broadcast_messages
 ```
 
+Parameters:
+
 | Attribute   | Type     | Required | Description                                           |
-| ----------- | -------- | -------- | ---------------------------------------------------- |
-| `message`   | string   | yes      | Message to display                                   |
-| `starts_at` | datetime | no       | Starting time (defaults to current time)             |
-| `ends_at`   | datetime | no       | Ending time (defaults to one hour from current time) |
-| `color`     | string   | no       | Background color hex code                            |
-| `font`      | string   | no       | Foreground color hex code                            |
-
-```bash
+|:------------|:---------|:---------|:------------------------------------------------------|
+| `message`   | string   | yes      | Message to display.                                   |
+| `starts_at` | datetime | no       | Starting time (defaults to current time).             |
+| `ends_at`   | datetime | no       | Ending time (defaults to one hour from current time). |
+| `color`     | string   | no       | Background color hex code.                            |
+| `font`      | string   | no       | Foreground color hex code.                            |
+
+Example request:
+
+```sh
 curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages
 ```
 
@@ -94,20 +113,26 @@ Example response:
 
 ## Update a broadcast message
 
-```
+Update an existing broadcast message.
+
+```text
 PUT /broadcast_messages/:id
 ```
 
+Parameters:
+
 | Attribute   | Type     | Required | Description                        |
-| ----------- | -------- | -------- | ------------------------- |
-| `id`        | integer  | yes      | Broadcast message ID      |
-| `message`   | string   | no       | Message to display        |
-| `starts_at` | datetime | no       | Starting time             |
-| `ends_at`   | datetime | no       | Ending time               |
-| `color`     | string   | no       | Background color hex code |
-| `font`      | string   | no       | Foreground color hex code |
-
-```bash
+|:------------|:---------|:---------|:-----------------------------------|
+| `id`        | integer  | yes      | ID of broadcast message to update. |
+| `message`   | string   | no       | Message to display.                |
+| `starts_at` | datetime | no       | Starting time.                     |
+| `ends_at`   | datetime | no       | Ending time.                       |
+| `color`     | string   | no       | Background color hex code.         |
+| `font`      | string   | no       | Foreground color hex code.         |
+
+Example request:
+
+```sh
 curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
 ```
 
@@ -127,14 +152,20 @@ Example response:
 
 ## Delete a broadcast message
 
-```
+Delete a broadcast message.
+
+```sh
 DELETE /broadcast_messages/:id
 ```
 
+Parameters:
+
 | Attribute | Type    | Required | Description                        |
-| ----------- | -------- | -------- | ------------------------- |
-| `id`        | integer  | yes      | Broadcast message ID      |
+|:----------|:--------|:---------|:-----------------------------------|
+| `id`      | integer | yes      | ID of broadcast message to delete. |
+
+Example request:
 
-```bash
+```sh
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1
 ```

doc/api/snippets.md

 # Snippets API
 
-> [Introduced][ce-6373] in GitLab 8.15.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373) in GitLab 8.15.
+
+Snippets API operates on [snippets](../user/snippets.md).
 
 ## Snippet visibility level
 
 Snippets in GitLab can be either private, internal, or public.
 You can set it with the `visibility` field in the snippet.
 
-Constants for snippet visibility levels are:
+Valid values for snippet visibility levels are:
 
 | Visibility | Description                                         |
-| ---------- | ----------- |
-| `private`  | The snippet is visible only to the snippet creator |
-| `internal` | The snippet is visible for any logged in user |
-| `public`   | The snippet can be accessed without any authentication |
+|:-----------|:----------------------------------------------------|
+| `private`  | Snippet is visible only to the snippet creator.     |
+| `internal` | Snippet is visible for any logged in user.          |
+| `public`   | Snippet can be accessed without any authentication. |
 
-## List snippets
+## List all snippets for a user
 
-Get a list of current user's snippets.
+Get a list of the current user's snippets.
 
-```
+```text
 GET /snippets
 ```
 
-## Single snippet
+Example request:
 
-Get a single snippet.
+```sh
+curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets
+```
+
+Example response:
 
+```json
+[
+    {
+        "id": 42,
+        "title": "Voluptatem iure ut qui aut et consequatur quaerat.",
+        "file_name": "mclaughlin.rb",
+        "description": null,
+        "visibility": "internal",
+        "author": {
+            "id": 22,
+            "name": "User 0",
+            "username": "user0",
+            "state": "active",
+            "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",
+            "web_url": "http://localhost:3000/user0"
+        },
+        "updated_at": "2018-09-18T01:12:26.383Z",
+        "created_at": "2018-09-18T01:12:26.383Z",
+        "project_id": null,
+        "web_url": "http://localhost:3000/snippets/42",
+        "raw_url": "http://localhost:3000/snippets/42/raw"
+    },
+    {
+        "id": 41,
+        "title": "Ut praesentium non et atque.",
+        "file_name": "ondrickaemard.rb",
+        "description": null,
+        "visibility": "internal",
+        "author": {
+            "id": 22,
+            "name": "User 0",
+            "username": "user0",
+            "state": "active",
+            "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",
+            "web_url": "http://localhost:3000/user0"
+        },
+        "updated_at": "2018-09-18T01:12:26.360Z",
+        "created_at": "2018-09-18T01:12:26.360Z",
+        "project_id": null,
+        "web_url": "http://localhost:3000/snippets/41",
+        "raw_url": "http://localhost:3000/snippets/41/raw"
+    }
+]
 ```
+
+## Get a single snippet
+
+Get a single snippet.
+
+```text
 GET /snippets/:id
 ```
 
 Parameters:
 
 | Attribute | Type    | Required | Description                |
-| ---------          | ----    | -------- | -----------                   |
-| `id`               | Integer | yes      | The ID of a snippet           |
+|:----------|:--------|:---------|:---------------------------|
+| `id`      | integer | yes      | ID of snippet to retrieve. |
+
+Example request:
 
-```bash
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1
 ```
 
@@ -69,46 +126,52 @@ Example response:
 
 Get a single snippet's raw contents.
 
-```
+```text
 GET /snippets/:id/raw
 ```
 
 Parameters:
 
 | Attribute | Type    | Required | Description                |
-| ---------          | ----    | -------- | -----------                   |
-| `id`               | Integer | yes      | The ID of a snippet           |
+|:----------|:--------|:---------|:---------------------------|
+| `id`      | integer | yes      | ID of snippet to retrieve. |
+
+Example request:
 
-```bash
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/raw
 ```
 
 Example response:
 
-```
+```text
 Hello World snippet
 ```
 
 ## Create new snippet
 
-Creates a new snippet. The user must have permission to create new snippets.
+Create a new snippet.
 
-```
+NOTE: **Note:**
+The user must have permission to create new snippets.
+
+```text
 POST /snippets
 ```
 
 Parameters:
 
 | Attribute     | Type   | Required | Description                                        |
-| ---------          | ----    | -------- | -----------                  |
-| `title`            | String  | yes      | The title of a snippet       |
-| `file_name`        | String  | yes      | The name of a snippet file   |
-| `content`          | String  | yes      | The content of a snippet     |
-| `description`      | String  | no       | The description of a snippet |
-| `visibility`       | String  | no       | The snippet's visibility     |
+|:--------------|:-------|:---------|:---------------------------------------------------|
+| `title`       | string | yes      | Title of a snippet.                                |
+| `file_name`   | string | yes      | Name of a snippet file.                            |
+| `content`     | string | yes      | Content of a snippet.                              |
+| `description` | string | no       | Description of a snippet.                          |
+| `visibility`  | string | no       | Snippet's [visibility](#snippet-visibility-level). |
 
+Example request:
 
-```bash
+```sh
 curl --request POST \
      --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \
      --header 'Content-Type: application/json' \
@@ -142,25 +205,29 @@ Example response:
 
 ## Update snippet
 
-Updates an existing snippet. The user must have permission to change an existing snippet.
+Update an existing snippet.
 
-```
+NOTE: **Note:**
+The user must have permission to change an existing snippet.
+
+```text
 PUT /snippets/:id
 ```
 
 Parameters:
 
 | Attribute     | Type    | Required | Description                                        |
-| ---------          | ----    | -------- | -----------                  |
-| `id`               | Integer | yes      | The ID of a snippet          |
-| `title`            | String  | no       | The title of a snippet       |
-| `file_name`        | String  | no       | The name of a snippet file   |
-| `description`      | String  | no       | The description of a snippet |
-| `content`          | String  | no       | The content of a snippet     |
-| `visibility`       | String  | no       | The snippet's visibility     |
+|:--------------|:--------|:---------|:---------------------------------------------------|
+| `id`          | integer | yes      | ID of snippet to update.                           |
+| `title`       | string  | no       | Title of a snippet.                                |
+| `file_name`   | string  | no       | Name of a snippet file.                            |
+| `description` | string  | no       | Description of a snippet.                          |
+| `content`     | string  | no       | Content of a snippet.                              |
+| `visibility`  | string  | no       | Snippet's [visibility](#snippet-visibility-level). |
 
+Example request:
 
-```bash
+```sh
 curl --request PUT \
      --data '{"title": "foo", "content": "bar"}' \
      --header 'Content-Type: application/json' \
@@ -194,38 +261,49 @@ Example response:
 
 ## Delete snippet
 
-Deletes an existing snippet.
+Delete an existing snippet.
 
-```
+```text
 DELETE /snippets/:id
 ```
 
 Parameters:
 
 | Attribute | Type    | Required | Description              |
-| ---------          | ----    | -------- | -----------                   |
-| `id`               | Integer | yes      | The ID of a snippet           |
+|:----------|:--------|:---------|:-------------------------|
+| `id`      | integer | yes      | ID of snippet to delete. |
 
+Example request:
 
-```
+```sh
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1"
 ```
 
-upon successful delete a `204 No content` HTTP code shall be expected, with no data,
-but if the snippet is non-existent, a `404 Not Found` will be returned.
+The following are possible return codes:
 
-## Explore all public snippets
+| Code  | Description                                 |
+|:------|:--------------------------------------------|
+| `204` | Delete was successful. No data is returned. |
+| `404` | The snippet wasn't found.                   |
 
-```
+## List all public snippets
+
+List all public snippets.
+
+```text
 GET /snippets/public
 ```
 
+Parameters:
+
 | Attribute  | Type    | Required | Description                            |
-| ---------  | ----    | -------- | -----------                           |
-| `per_page` | Integer | no       | number of snippets to return per page |
-| `page`     | Integer | no       | the page to retrieve                  |
+|:-----------|:--------|:---------|:---------------------------------------|
+| `per_page` | integer | no       | Number of snippets to return per page. |
+| `page`     | integer | no       | Page to retrieve.                      |
 
-```bash
+Example request:
+
+```sh
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1
 ```
 
@@ -273,21 +351,22 @@ Example response:
 
 ## Get user agent details
 
-> **Notes:**
-> [Introduced][ce-29508] in GitLab 9.4.
-
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655) in GitLab 9.4.
 
-Available only for admins.
+NOTE: **Note:**
+Available only for administrators.
 
-```
+```text
 GET /snippets/:id/user_agent_detail
 ```
 
 | Attribute | Type    | Required | Description    |
-|-------------|---------|----------|--------------------------------------|
-| `id`        | Integer | yes      | The ID of a snippet                  |
+|:----------|:--------|:---------|:---------------|
+| `id`      | integer | yes      | ID of snippet. |
 
-```bash
+Example request:
+
+```sh
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/user_agent_detail
 ```
 
@@ -300,6 +379,3 @@ Example response:
   "akismet_submitted": false
 }
 ```
-
-[ce-6373]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373
-[ce-29508]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655

doc/ci/variables/README.md

@@ -70,7 +70,7 @@ future GitLab releases.**
 | **CI_DEPLOY_PASSWORD**                    | 10.8   | all    | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
 | **CI_DEPLOY_USER**                        | 10.8   | all    | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
 | **CI_DISPOSABLE_ENVIRONMENT**             | all    | 10.1   | Marks that the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. |
-| **CI_ENVIRONMENT_NAME**                   | 8.15   | all    | The name of the environment for this job. Only present if [`environment:name`](../yaml/README.md#environmenturl) is set. |
+| **CI_ENVIRONMENT_NAME**                   | 8.15   | all    | The name of the environment for this job. Only present if [`environment:name`](../yaml/README.md#environmentname) is set. |
 | **CI_ENVIRONMENT_SLUG**                   | 8.15   | all    | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. Only present if [`environment:name`](../yaml/README.md#environmentname) is set. |
 | **CI_ENVIRONMENT_URL**                    | 9.3    | all    | The URL of the environment for this job. Only present if [`environment:url`](../yaml/README.md#environmenturl) is set. |
 | **CI_JOB_ID**                             | 9.0    | all    | The unique id of the current job that GitLab CI uses internally |

doc/user/admin_area/broadcast_messages.md

@@ -4,6 +4,8 @@ GitLab can display messages to all users of a GitLab instance in a banner that a
 
 ![Broadcast Message](img/broadcast_messages.png)
 
+Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md).
+
 NOTE: **Note:**
 If more than one banner message is active at one time, they are displayed in a stack in order of creation.
 

doc/user/snippets.md

@@ -4,7 +4,12 @@ With GitLab Snippets you can store and share bits of code and text with other us
 
 ![GitLab Snippet](img/gitlab_snippet.png)
 
-There are 2 types of snippets, personal snippets and project snippets.
+Snippets can be maintained using [snippets API](../api/snippets.md).
+
+There are two types of snippets:
+
+- Personal snippets.
+- Project snippets.
 
 ## Personal snippets