diff options
Diffstat (limited to 'doc')
46 files changed, 1116 insertions, 193 deletions
diff --git a/doc/README.md b/doc/README.md index 57d85d770e7..df11d5e49a8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,8 +1,17 @@ -# GitLab Community Edition documentation +# GitLab Community Edition -## University +All technical content published by GitLab lives in the documentation, including: -[University](university/README.md) contain guides to learn Git and GitLab through courses and videos. +- **General Documentation** + - [User docs](#user-documentation): general documentation dedicated to regular users of GitLab + - [Admin docs](#administrator-documentation): general documentation dedicated to administrators of GitLab instances + - [Contributor docs](#contributor-documentation): general documentation on how to develop and contribute to GitLab +- [Topics](topics/index.md): pages organized per topic, gathering all the + resources already published by GitLab related to a specific subject, including + general docs, [technical articles](development/writing_documentation.md#technical-articles), + blog posts and video tutorials. +- [GitLab University](university/README.md): guides to learn Git and GitLab + through courses and videos. ## User documentation diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 30a4c08508d..2e22212ddde 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -2,7 +2,7 @@ [Gitaly](https://gitlab.com/gitlab-org/gitlay) (introduced in GitLab 9.0) is a service that provides high-level RPC access to Git -repositories. As of GitLab 9.0 it is still an optional component with +repositories. As of GitLab 9.1 it is still an optional component with limited scope. GitLab components that access Git repositories (gitlab-rails, @@ -11,28 +11,26 @@ not have direct access to Gitaly. ## Configuring Gitaly -The Gitaly service itself is configured via environment variables. -These variables are documented [in the gitaly +The Gitaly service itself is configured via a TOML configuration file. +This file is documented [in the gitaly repository](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md). -To change a Gitaly environment variable in Omnibus you can use -`gitaly['env']` in `/etc/gitlab/gitlab.rb`. Changes will be applied +To change a Gitaly setting in Omnibus you can use +`gitaly['my_setting']` in `/etc/gitlab/gitlab.rb`. Changes will be applied when you run `gitlab-ctl reconfigure`. ```ruby -gitaly['env'] = { - 'GITALY_MY_VARIABLE' => 'value' -} +gitaly['prometheus_listen_addr'] = 'localhost:9236' ``` -To change a Gitaly environment variable in installations from source -you can edit `/home/git/gitaly/env`. +To change a Gitaly setting in installations from source you can edit +`/home/git/gitaly/config.toml`. -```shell -GITALY_MY_VARIABLE='value' +```toml +prometheus_listen_addr = "localhost:9236" ``` -Changes to `/home/git/gitaly/env` are applied when you run `service +Changes to `/home/git/gitaly/config.toml` are applied when you run `service gitlab restart`. ## Configuring GitLab to not use Gitaly @@ -49,15 +47,15 @@ gitaly['enable'] = false ``` In source installations, edit `/home/git/gitlab/config/gitlab.yml` and -make sure `socket_path` in the `gitaly` section is commented out. This -does not disable the Gitaly service; it only prevents it from being -used. +make sure `enabled` in the `gitaly` section is set to 'false'. This +does not disable the Gitaly service in your init script; it only +prevents it from being used. Apply the change with `service gitlab restart`. ```yaml gitaly: - # socket_path: tmp/sockets/private/gitlay.socket + enabled: false ``` ## Disabling or enabling the Gitaly service diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index cf3aca106e9..c22b1af8bfb 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -13,8 +13,8 @@ Database Service (RDS) that runs PostgreSQL. If you use a cloud-managed service, or provide your own PostgreSQL: -1. Setup PostgreSQL according to the - [database requirements document](doc/install/requirements.md#database). +1. Setup PostgreSQL according to the + [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. 1. Configure the GitLab application servers with the appropriate details. diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md new file mode 100644 index 00000000000..affb4d17861 --- /dev/null +++ b/doc/administration/raketasks/github_import.md @@ -0,0 +1,36 @@ +# GitHub import + +>**Note:** +> +> - [Introduced][ce-10308] in GitLab 9.1. +> - You need a personal access token in order to retrieve and import GitHub +> projects. You can get it from: https://github.com/settings/tokens +> - You also need to pass an username as the second argument to the rake task +> which will become the owner of the project. + +To import a project from the list of your GitHub projects available: + +```bash +# Omnibus installations +sudo gitlab-rake import:github[access_token,root,foo/bar] + +# Installations from source +bundle exec rake import:github[access_token,root,foo/bar] RAILS_ENV=production +``` + +In this case, `access_token` is your GitHub personal access token, `root` +is your GitLab username, and `foo/bar` is the new GitLab namespace/project that +will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. + + +To import a specific GitHub project (named `foo/github_repo` here): + +```bash +# Omnibus installations +sudo gitlab-rake import:github[access_token,root,foo/bar,foo/github_repo] + +# Installations from source +bundle exec rake import:github[access_token,root,foo/bar,foo/github_repo] RAILS_ENV=production +``` + +[ce-10308]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308 diff --git a/doc/api/issues.md b/doc/api/issues.md index a19c965a8c3..54c099d4bf8 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -26,16 +26,18 @@ GET /issues?labels=foo,bar&state=opened GET /issues?milestone=1.0.0 GET /issues?milestone=1.0.0&state=opened GET /issues?iids[]=42&iids[]=43 +GET /issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string| no | The milestone title | -| `iids` | Array[integer] | no | Return only the issues having the given `iid` | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `milestone` | string | no | The milestone title | +| `iids` | Array[integer] | no | Return only the issues having the given `iid` | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search issues against their `title` and `description` | ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues @@ -104,17 +106,19 @@ GET /groups/:id/issues?labels=foo,bar&state=opened GET /groups/:id/issues?milestone=1.0.0 GET /groups/:id/issues?milestone=1.0.0&state=opened GET /groups/:id/issues?iids[]=42&iids[]=43 +GET /groups/:id/issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a group | -| `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `iids` | Array[integer] | no | Return only the issues having the given `iid` | -| `milestone` | string| no | The milestone title | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a group | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `iids` | Array[integer] | no | Return only the issues having the given `iid` | +| `milestone` | string | no | The milestone title | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search group issues against their `title` and `description` | ```bash @@ -184,17 +188,19 @@ GET /projects/:id/issues?labels=foo,bar&state=opened GET /projects/:id/issues?milestone=1.0.0 GET /projects/:id/issues?milestone=1.0.0&state=opened GET /projects/:id/issues?iids[]=42&iids[]=43 +GET /projects/:id/issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `iids` | Array[integer] | no | Return only the milestone having the given `iid` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string| no | The milestone title | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `iids` | Array[integer] | no | Return only the milestone having the given `iid` | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `milestone` | string | no | The milestone title | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search project issues against their `title` and `description` | ```bash @@ -259,7 +265,7 @@ GET /projects/:id/issues/:issue_iid ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | @@ -323,19 +329,19 @@ Creates a new project issue. POST /projects/:id/issues ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `title` | string | yes | The title of an issue | -| `description` | string | no | The description of an issue | -| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | -| `assignee_id` | integer | no | The ID of a user to assign issue | -| `milestone_id` | integer | no | The ID of a milestone to assign issue | -| `labels` | string | no | Comma-separated label names for an issue | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | -| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | -| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values. | -| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +| Attribute | Type | Required | Description | +|-------------------------------------------|---------|----------|--------------| +| `id` | integer | yes | The ID of a project | +| `title` | string | yes | The title of an issue | +| `description` | string | no | The description of an issue | +| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | +| `assignee_id` | integer | no | The ID of a user to assign issue | +| `milestone_id` | integer | no | The ID of a milestone to assign issue | +| `labels` | string | no | Comma-separated label names for an issue | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | +| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.| +| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug @@ -384,7 +390,7 @@ PUT /projects/:id/issues/:issue_iid ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|----------------|---------|----------|------------------------------------------------------------------------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `title` | string | no | The title of an issue | @@ -443,7 +449,7 @@ DELETE /projects/:id/issues/:issue_iid ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | @@ -465,7 +471,7 @@ POST /projects/:id/issues/:issue_iid/move ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-----------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `to_project_id` | integer | yes | The ID of the new project | @@ -521,7 +527,7 @@ POST /projects/:id/issues/:issue_iid/subscribe ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | @@ -576,7 +582,7 @@ POST /projects/:id/issues/:issue_iid/unsubscribe ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | @@ -595,7 +601,7 @@ POST /projects/:id/issues/:issue_iid/todo ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | @@ -686,7 +692,7 @@ POST /projects/:id/issues/:issue_iid/time_estimate ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `duration` | string | yes | The duration in human format. e.g: 3h30m | @@ -715,7 +721,7 @@ POST /projects/:id/issues/:issue_iid/reset_time_estimate ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | @@ -743,7 +749,7 @@ POST /projects/:id/issues/:issue_iid/add_spent_time ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `duration` | string | yes | The duration in human format. e.g: 3h30m | @@ -772,7 +778,7 @@ POST /projects/:id/issues/:issue_iid/reset_spent_time ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | @@ -798,7 +804,7 @@ GET /projects/:id/issues/:issue_iid/time_stats ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | diff --git a/doc/api/labels.md b/doc/api/labels.md index e8c220f6809..839000a4f48 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -90,7 +90,7 @@ POST /projects/:id/labels | ------------- | ------- | -------- | ---------------------------- | | `id` | integer | yes | The ID of the project | | `name` | string | yes | The name of the label | -| `color` | string | yes | The color of the label in 6-digit hex notation with leading `#` sign | +| `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label | | `priority` | integer | no | The priority of the label. Must be greater or equal than zero or `null` to remove the priority. | @@ -145,7 +145,7 @@ PUT /projects/:id/labels | `id` | integer | yes | The ID of the project | | `name` | string | yes | The name of the existing label | | `new_name` | string | yes if `color` is not provided | The new name of the label | -| `color` | string | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign | +| `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The new description of the label | | `priority` | integer | no | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. | diff --git a/doc/api/notes.md b/doc/api/notes.md index 6ef06b2c2e9..5e927143714 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -9,13 +9,13 @@ Notes are comments on snippets, issues or merge requests. Gets a list of all notes for a single issue. ``` -GET /projects/:id/issues/:issue_id/notes +GET /projects/:id/issues/:issue_iid/notes ``` Parameters: - `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue +- `issue_iid` (required) - The IID of an issue ```json [ @@ -63,13 +63,13 @@ Parameters: Returns a single note for a specific project issue ``` -GET /projects/:id/issues/:issue_id/notes/:note_id +GET /projects/:id/issues/:issue_iid/notes/:note_id ``` Parameters: - `id` (required) - The ID of a project -- `issue_id` (required) - The ID of a project issue +- `issue_iid` (required) - The IID of a project issue - `note_id` (required) - The ID of an issue note ### Create new issue note @@ -78,13 +78,13 @@ Creates a new note to a single project issue. If you create a note where the bod only contains an Award Emoji, you'll receive this object back. ``` -POST /projects/:id/issues/:issue_id/notes +POST /projects/:id/issues/:issue_iid/notes ``` Parameters: - `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue +- `issue_id` (required) - The IID of an issue - `body` (required) - The content of a note - `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z @@ -93,13 +93,13 @@ Parameters: Modify existing note of an issue. ``` -PUT /projects/:id/issues/:issue_id/notes/:note_id +PUT /projects/:id/issues/:issue_iid/notes/:note_id ``` Parameters: - `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue +- `issue_iid` (required) - The IID of an issue - `note_id` (required) - The ID of a note - `body` (required) - The content of a note @@ -108,7 +108,7 @@ Parameters: Deletes an existing note of an issue. ``` -DELETE /projects/:id/issues/:issue_id/notes/:note_id +DELETE /projects/:id/issues/:issue_iid/notes/:note_id ``` Parameters: @@ -116,7 +116,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of a project | -| `issue_id` | integer | yes | The ID of an issue | +| `issue_iid` | integer | yes | The IID of an issue | | `note_id` | integer | yes | The ID of a note | ```bash @@ -228,26 +228,26 @@ curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://git Gets a list of all notes for a single merge request. ``` -GET /projects/:id/merge_requests/:merge_request_id/notes +GET /projects/:id/merge_requests/:merge_request_iid/notes ``` Parameters: - `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a project merge request +- `merge_request_iid` (required) - The IID of a project merge request ### Get single merge request note Returns a single note for a given merge request. ``` -GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id +GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` Parameters: - `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a project merge request +- `merge_request_iid` (required) - The IID of a project merge request - `note_id` (required) - The ID of a merge request note ```json @@ -278,13 +278,13 @@ If you create a note where the body only contains an Award Emoji, you'll receive this object back. ``` -POST /projects/:id/merge_requests/:merge_request_id/notes +POST /projects/:id/merge_requests/:merge_request_iid/notes ``` Parameters: - `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a merge request +- `merge_request_iid` (required) - The IID of a merge request - `body` (required) - The content of a note ### Modify existing merge request note @@ -292,13 +292,13 @@ Parameters: Modify existing note of a merge request. ``` -PUT /projects/:id/merge_requests/:merge_request_id/notes/:note_id +PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` Parameters: - `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a merge request +- `merge_request_iid` (required) - The IID of a merge request - `note_id` (required) - The ID of a note - `body` (required) - The content of a note @@ -307,7 +307,7 @@ Parameters: Deletes an existing note of a merge request. ``` -DELETE /projects/:id/merge_requests/:merge_request_id/notes/:note_id +DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id ``` Parameters: @@ -315,7 +315,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of a project | -| `merge_request_id` | integer | yes | The ID of a merge request | +| `merge_request_iid` | integer | yes | The IID of a merge request | | `note_id` | integer | yes | The ID of a note | ```bash diff --git a/doc/api/settings.md b/doc/api/settings.md index ad975e2e325..d99695ca986 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -48,7 +48,8 @@ Example response: "koding_url": null, "plantuml_enabled": false, "plantuml_url": null, - "terminal_max_session_time": 0 + "terminal_max_session_time": 0, + "polling_interval_multiplier": 1.0 } ``` @@ -88,6 +89,7 @@ PUT /application/settings | `plantuml_enabled` | boolean | no | Enable PlantUML integration. Default is `false`. | | `plantuml_url` | string | yes (if `plantuml_enabled` is `true`) | The PlantUML instance URL for integration. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to 0 for unlimited time. | +| `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to 0 to disable polling. | ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal @@ -124,6 +126,7 @@ Example response: "koding_url": null, "plantuml_enabled": false, "plantuml_url": null, - "terminal_max_session_time": 0 + "terminal_max_session_time": 0, + "polling_interval_multiplier": 1.0 } ``` diff --git a/doc/ci/README.md b/doc/ci/README.md index d8fba5d7a77..b3780a08828 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,34 +1,147 @@ -# GitLab CI Documentation +# GitLab Continuous Integration (GitLab CI) -## CI User documentation + + +The benefits of Continuous Integration are huge when automation plays an +integral part of your workflow. GitLab comes with built-in Continuous +Integration, Continuous Deployment, and Continuous Delivery support to build, +test, and deploy your application. + +Here's some info we've gathered to get you started. + +## Getting started + +The first steps towards your GitLab CI journey. - [Getting started with GitLab CI](quick_start/README.md) -- [CI examples for various languages](examples/README.md) -- [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) - [Pipelines and jobs](pipelines.md) -- [Environments and deployments](environments.md) -- [Learn how `.gitlab-ci.yml` works](yaml/README.md) - [Configure a Runner, the application that runs your jobs](runners/README.md) -- [Use Docker images with GitLab Runner](docker/using_docker_images.md) -- [Use CI to build Docker images](docker/using_docker_build.md) +- **Articles:** + - [Getting started with GitLab and GitLab CI - Intro to CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/) + - [Continuous Integration, Delivery, and Deployment with GitLab - Intro to CI/CD](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) + - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) + - [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) + - [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) +- **Videos:** + - [Demo (March, 2017): how to get started using CI/CD with GitLab](https://about.gitlab.com/2017/03/13/ci-cd-demo/) + - [Webcast (April, 2016): getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/) +- **Third-party videos:** + - [Intégration continue avec GitLab (September, 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s) + - [GitLab CI for Minecraft Plugins (July, 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8) + +## Reference guides + +Once you get familiar with the getting started guides, you'll find yourself +digging into specific reference guides. + +- [`.gitlab-ci.yml` reference](yaml/README.md) - Learn all about the ins and + outs of `.gitlab-ci.yml` definitions - [CI Variables](variables/README.md) - Learn how to use variables defined in your `.gitlab-ci.yml` or secured ones defined in your project's settings -- [Use SSH keys in your build environment](ssh_keys/README.md) -- [Trigger jobs through the API](triggers/README.md) +- **The permissions model** - Learn about the access levels a user can have for + performing certain CI actions + - [User permissions](../user/permissions.md#gitlab-ci) + - [Jobs permissions](../user/permissions.md#jobs-permissions) + +## GitLab CI + Docker + +Leverage the power of Docker to run your CI pipelines. + +- [Use Docker images with GitLab Runner](docker/using_docker_images.md) +- [Use CI to build Docker images](docker/using_docker_build.md) +- [CI services (linked Docker containers)](services/README.md) +- **Articles:** + - [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) + +## Advanced use + +Once you get familiar with the basics of GitLab CI, it's time to dive in and +learn how to leverage its potential even more. + +- [Environments and deployments](environments.md) - Separate your jobs into + environments and use them for different purposes like testing, building and + deploying - [Job artifacts](../user/project/pipelines/job_artifacts.md) -- [User permissions](../user/permissions.md#gitlab-ci) -- [Jobs permissions](../user/permissions.md#jobs-permissions) -- [API](../api/ci/README.md) -- [CI services (linked docker containers)](services/README.md) -- [CI/CD pipelines settings](../user/project/pipelines/settings.md) -- [Review Apps](review_apps/index.md) -- [Git submodules](git_submodules.md) Using Git submodules in your CI jobs +- [Git submodules](git_submodules.md) - How to run your CI jobs when Git + submodules are involved - [Auto deploy](autodeploy/index.md) +- [Use SSH keys in your build environment](ssh_keys/README.md) +- [Trigger jobs through the GitLab API](triggers/README.md) + +## Review Apps + +- [Review Apps](review_apps/index.md) +- **Articles:** + - [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/) + - [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/) + +## GitLab CI for GitLab Pages + +See the topic on [GitLab Pages](../user/project/pages/index.md). + +## Special configuration + +You can change the default behavior of GitLab CI in your whole GitLab instance +as well as in each project. + +- **Project specific** + - [CI/CD pipelines settings](../user/project/pipelines/settings.md) + - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) +- **Affecting the whole GitLab instance** + - [Continuous Integration admin settings](../user/admin_area/settings/continuous_integration.md) + +## Examples + +>**Note:** +A collection of `.gitlab-ci.yml` files is maintained at the +[GitLab CI Yml project][gitlab-ci-templates]. +If your favorite programming language or framework is missing we would love +your help by sending a merge request with a `.gitlab-ci.yml`. + +Here is an collection of tutorials and guides on setting up your CI pipeline. + +- [GitLab CI examples](examples/README.md) for the following languages and frameworks: + - [PHP](examples/php.md) + - [Ruby](examples/test-and-deploy-ruby-application-to-heroku.md) + - [Python](examples/test-and-deploy-python-application-to-heroku.md) + - [Clojure](examples/test-clojure-application.md) + - [Scala](examples/test-scala-application.md) + - [Phoenix](examples/test-phoenix-application.md) + - [Run PHP Composer & NPM scripts then deploy them to a staging server](examples/deployment/composer-npm-deploy.md) +- **Blog posts** + - [Automated Debian packaging](https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/) + - [Spring boot application with GitLab CI and Kubernetes](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/) + - [Setting up CI for iOS projects](https://about.gitlab.com/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/) + - [Using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) + - [Setting up GitLab CI for Android projects](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/) + - [Building a new GitLab Docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) + - [CI/CD with GitLab in action](https://about.gitlab.com/2017/03/13/ci-cd-demo/) + - [Building an Elixir Release into a Docker image using GitLab CI](https://about.gitlab.com/2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/) +- **Miscellaneous** + - [Using `dpl` as deployment tool](examples/deployment/README.md) + - [Repositories with examples for various languages](https://gitlab.com/groups/gitlab-examples) + - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml) + - [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/) + +## Integrations + +- **Articles:** + - [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/) + - [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/) + - [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/) + +## Why GitLab CI? + +- **Articles:** + - [Why We Chose GitLab CI for our CI/CD Solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/) + - [Building our web-app on GitLab CI: 5 reasons why Captain Train migrated from Jenkins to GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/) ## Breaking changes -- [CI variables renaming](variables/README.md#9-0-renaming) Read about the +- [CI variables renaming for GitLab 9.0](variables/README.md#9-0-renaming) Read about the deprecated CI variables and what you should use for GitLab 9.0+. - [New CI job permissions model](../user/project/new_ci_build_permissions_model.md) Read about what changed in GitLab 8.12 and how that affects your jobs. There's a new way to access your Git submodules and LFS objects in jobs. + +[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index edb315d5b84..ffa0831290a 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -299,8 +299,8 @@ could look like: stage: build script: - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com - - docker build -t registry.example.com/group/project:latest . - - docker push registry.example.com/group/project:latest + - docker build -t registry.example.com/group/project/image:latest . + - docker push registry.example.com/group/project/image:latest ``` You have to use the special `gitlab-ci-token` user created for you in order to @@ -350,8 +350,8 @@ stages: - deploy variables: - CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project:$CI_COMMIT_REF_NAME - CONTAINER_RELEASE_IMAGE: registry.example.com/my-group/my-project:latest + CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project/my-image:$CI_COMMIT_REF_NAME + CONTAINER_RELEASE_IMAGE: registry.example.com/my-group/my-project/my-image:latest before_script: - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 5377bf9ee80..33c27b39a8a 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -1,4 +1,4 @@ -# CI Examples +# GitLab CI Examples A collection of `.gitlab-ci.yml` files is maintained at the [GitLab CI Yml project][gitlab-ci-templates]. If your favorite programming language or framework are missing we would love your help by sending a merge request @@ -6,22 +6,73 @@ with a `.gitlab-ci.yml`. Apart from those, here is an collection of tutorials and guides on setting up your CI pipeline: +## Languages, frameworks, OSs + +### PHP + - [Testing a PHP application](php.md) +- [Run PHP Composer & NPM scripts then deploy them to a staging server](deployment/composer-npm-deploy.md) + +### Ruby + - [Test and deploy a Ruby application to Heroku](test-and-deploy-ruby-application-to-heroku.md) + +### Python + - [Test and deploy a Python application to Heroku](test-and-deploy-python-application-to-heroku.md) -- [Test a Clojure application](test-clojure-application.md) + +### Java + +- **Articles:** + - [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/) + +### Scala + - [Test a Scala application](test-scala-application.md) + +### Clojure + +- [Test a Clojure application](test-clojure-application.md) + +### Elixir + - [Test a Phoenix application](test-phoenix-application.md) -- [Using `dpl` as deployment tool](deployment/README.md) -- [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/) -- [Run PHP Composer & NPM scripts then deploy them to a staging server](deployment/composer-npm-deploy.md) -- Help your favorite programming language and GitLab by sending a merge request - with a guide for that language. +- **Articles:** + - [Building an Elixir Release into a Docker image using GitLab CI](https://about.gitlab.com/2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/) + +### iOS + +- **Articles:** + - [Setting up GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) + +### Android -## Outside the documentation +- **Articles:** + - [Setting up GitLab CI for Android projects](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/) -- [Blog post about using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) +### Other + +- [Using `dpl` as deployment tool](deployment/README.md) - [Repositories with examples for various languages](https://gitlab.com/groups/gitlab-examples) - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml) +- **Articles:** + - [Continuous Deployment with GitLab: how to build and deploy a Debian Package with GitLab CI](https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/) + +## GitLab CI for GitLab Pages + +- [Example projects](https://gitlab.com/pages) +- **Articles:** + - [Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](../../user/project/pages/getting_started_part_four.md) + - [SSGs Part 3: Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/): + examples for Ruby-, NodeJS-, Python-, and GoLang-based SSGs + - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) + - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/) + +See the topic [GitLab Pages](../../user/project/pages/index.md) for a complete overview. + +## More + +Contributions are very much welcomed! You can help your favorite programming +language and GitLab by sending a merge request with a guide for that language. [gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index d28aa282825..7b0995597c4 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -1,20 +1,30 @@ -## Using Dpl as deployment tool -Dpl (dee-pee-ell) is a deploy tool made for continuous deployment that's developed and used by Travis CI, but can also be used with GitLab CI. +# Using Dpl as deployment tool -**We recommend to use Dpl, if you're deploying to any of these of these services: https://github.com/travis-ci/dpl#supported-providers**. +[Dpl](https://github.com/travis-ci/dpl) (dee-pee-ell) is a deploy tool made for +continuous deployment that's developed and used by Travis CI, but can also be +used with GitLab CI. -### Requirements -To use Dpl you need at least Ruby 1.8.7 with ability to install gems. +>**Note:** +We recommend to use Dpl if you're deploying to any of these of these services: +https://github.com/travis-ci/dpl#supported-providers. + +## Requirements + +To use Dpl you need at least Ruby 1.9.3 with ability to install gems. + +## Basic usage + +Dpl can be installed on any machine with: -### Basic usage -The Dpl can be installed on any machine with: ``` gem install dpl ``` -This allows you to test all commands from your shell, rather than having to test it on a CI server. +This allows you to test all commands from your local terminal, rather than +having to test it on a CI server. If you don't have Ruby installed you can do it on Debian-compatible Linux with: + ``` apt-get update apt-get install ruby-dev @@ -26,9 +36,10 @@ To use it simply define provider and any additional parameters required by the p For example if you want to use it to deploy your application to heroku, you need to specify `heroku` as provider, specify `api-key` and `app`. There's more and all possible parameters can be found here: https://github.com/travis-ci/dpl#heroku -``` +```yaml staging: - type: deploy + stage: deploy + script: - gem install dpl - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY ``` @@ -37,14 +48,17 @@ In the above example we use Dpl to deploy `my-app-staging` to Heroku server with To use different provider take a look at long list of [Supported Providers](https://github.com/travis-ci/dpl#supported-providers). -### Using Dpl with Docker +## Using Dpl with Docker + When you use GitLab Runner you most likely configured it to use your server's shell commands. This means that all commands are run in context of local user (ie. gitlab_runner or gitlab_ci_multi_runner). It also means that most probably in your Docker container you don't have the Ruby runtime installed. You will have to install it: -``` + +```yaml staging: - type: deploy + stage: deploy + script: - apt-get update -yq - apt-get install -y ruby-dev - gem install dpl @@ -53,24 +67,31 @@ staging: - master ``` -The first line `apt-get update -yq` updates the list of available packages, where second `apt-get install -y ruby-dev` install `Ruby` runtime on system. +The first line `apt-get update -yq` updates the list of available packages, +where second `apt-get install -y ruby-dev` installs the Ruby runtime on system. The above example is valid for all Debian-compatible systems. -### Usage in staging and production -It's pretty common in developer workflow to have staging (development) and production environment. -If we consider above example: we would like to deploy `master` branch to `staging` and `all tags` to `production` environment. +## Usage in staging and production + +It's pretty common in the development workflow to have staging (development) and +production environments + +Let's consider the following example: we would like to deploy the `master` +branch to `staging` and all tags to the `production` environment. The final `.gitlab-ci.yml` for that setup would look like this: -``` +```yaml staging: - type: deploy + stage: deploy + script: - gem install dpl - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY only: - master - + production: - type: deploy + stage: deploy + script: - gem install dpl - dpl --provider=heroku --app=my-app-production --api-key=$HEROKU_PRODUCTION_API_KEY only: @@ -78,21 +99,28 @@ production: ``` We created two deploy jobs that are executed on different events: + 1. `staging` is executed for all commits that were pushed to `master` branch, 2. `production` is executed for all pushed tags. We also use two secure variables: + 1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app, 2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. -### Storing API keys -In GitLab CI 7.12 a new feature was introduced: Secure Variables. -Secure Variables can added by going to `Project > Variables > Add Variable`. -**This feature requires `gitlab-runner` with version equal or greater than 0.4.0.** -The variables that are defined in the project settings are sent along with the build script to the runner. -The secure variables are stored out of the repository. Never store secrets in your projects' .gitlab-ci.yml. -It is also important that secret's value is hidden in the job log. +## Storing API keys + +Secure Variables can added by going to your project's +**Settings ➔ CI/CD Pipelines ➔ Secret variables**. The variables that are defined +in the project settings are sent along with the build script to the Runner. +The secure variables are stored out of the repository. Never store secrets in +your project's `.gitlab-ci.yml`. It is also important that the secret's value +is hidden in the job log. + +You access added variable by prefixing it's name with `$` (on non-Windows runners) +or `%` (for Windows Batch runners): -You access added variable by prefixing it's name with `$` (on non-Windows runners) or `%` (for Windows Batch runners): 1. `$SECRET_VARIABLE` - use it for non-Windows runners 2. `%SECRET_VARIABLE%` - use it for Windows Batch runners + +Read more about the [CI variables](../../variables/README.md). diff --git a/doc/ci/img/cicd_pipeline_infograph.png b/doc/ci/img/cicd_pipeline_infograph.png Binary files differnew file mode 100644 index 00000000000..9ddd4aa828b --- /dev/null +++ b/doc/ci/img/cicd_pipeline_infograph.png diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index b35caf672a8..53c29a4fd98 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -352,7 +352,7 @@ Example values: export CI_JOB_ID="50" export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a" export CI_COMMIT_REF_NAME="master" -export CI_REPOSITORY_URL="https://gitab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-ce.git" +export CI_REPOSITORY_URL="https://gitlab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-ce.git" export CI_COMMIT_TAG="1.0.0" export CI_JOB_NAME="spec:other" export CI_JOB_STAGE="test" diff --git a/doc/development/README.md b/doc/development/README.md index e27e7fc7d19..3c797505aa9 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -12,6 +12,8 @@ contributing to the API. - [Documentation styleguide](doc_styleguide.md) Use this styleguide if you are contributing to documentation. +- [Writing documentation](writing_documentation.md) + - [Distinction between general documentation and technical articles](writing_documentation.md#distinction-between-general-documentation-and-technical-articles) - [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations - [Testing standards and style guidelines](testing.md) - [UX guide](ux_guide/index.md) for building GitLab with existing CSS styles and elements diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 9bed441c131..bb78a0de0c5 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -3,6 +3,8 @@ This styleguide recommends best practices to improve documentation and to keep it organized and easy to find. +See also [writing documentation](writing_documentation.md). + ## Location and naming of documents >**Note:** @@ -27,6 +29,7 @@ The table below shows what kind of documentation goes where. | `doc/legal/` | Legal documents about contributing to GitLab. | | `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | | `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | +| `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`); Technical Articles: user guides, admin guides, technical overviews, tutorials (`doc/topics/topic-name/`). | --- @@ -56,6 +59,10 @@ The table below shows what kind of documentation goes where. own document located at `doc/user/admin_area/settings/`. For example, the **Visibility and Access Controls** category should have a document located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. +1. The `doc/topics/` directory holds topic-related technical content. Create + `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary. + Note that `topics` holds the index page per topic, and technical articles. General + user- and admin- related documentation, should be placed accordingly. --- diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 2d76bb18cff..9437a5f7a6e 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -17,8 +17,7 @@ polling rate. A `Poll-Interval: -1` means you should disable polling, and this must be implemented. 1. A response with HTTP status `4XX` or `5XX` should disable polling as well. 1. Use a common library for polling. -1. Poll on active tabs only. Use a common library to find out which tab currently has eyes on it. -Please use [Focus](https://gitlab.com/andrewn/focus). Specifically [Eyeballs Detector](https://gitlab.com/andrewn/focus/blob/master/lib/eyeballs-detector.js). +1. Poll on active tabs only. Please use [Visibility](https://github.com/ai/visibilityjs). 1. Use regular polling intervals, do not use backoff polling, or jitter, as the interval will be controlled by the server. 1. The backend code will most likely be using etags. You do not and should not check for status diff --git a/doc/development/fe_guide/testing.md b/doc/development/fe_guide/testing.md index bb6adeacc4c..8d3513d3566 100644 --- a/doc/development/fe_guide/testing.md +++ b/doc/development/fe_guide/testing.md @@ -7,7 +7,7 @@ feature tests with Capybara for integration testing. Feature tests need to be written for all new features. Regression tests ought to be written for all bug fixes to prevent them from recurring in the future. -See [the Testing Standards and Style Guidelines](/doc/development/testing.md) +See [the Testing Standards and Style Guidelines](../testing.md) for more information on general testing practices at GitLab. ## Karma test suite @@ -48,7 +48,7 @@ remove these directives when you commit your code. Information on setting up and running RSpec integration tests with [Capybara][capybara] can be found in the -[general testing guide](/doc/development/testing.md). +[general testing guide](../testing.md). ## Gotchas diff --git a/doc/development/img/cache-hit.svg b/doc/development/img/cache-hit.svg new file mode 100644 index 00000000000..1c37693df2d --- /dev/null +++ b/doc/development/img/cache-hit.svg @@ -0,0 +1,21 @@ +<svg version="1.1" id="mscgen_js-svg-__svg" class="mscgen_js-svg-__svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="976" height="310" viewBox="0 0 976 310"><desc> + +# Generated by mscgen_js - https://sverweij.github.io/mscgen_js +msc { + # options + hscale="1.5"; + + # entities + c [label="Client", textbgcolor="lime"], + rails [label="Rails", textbgcolor="cyan"], + etag [label="EtagCaching", textbgcolor="orange"], + redis [label="Redis", textbgcolor="white"]; + + # arcs + c => rails [label="GET /projects/5/pipelines"]; + rails => etag [label="GET /projects/5/pipelines"]; + etag => redis [label="read(key = 'GET <Etag>')"]; + redis => etag [label="cache hit", linecolor="green", textcolor="green"]; + |||; + etag => c [label="304 Not Modified", linecolor="blue", textcolor="blue"]; +}</desc><defs><style type="text/css">svg.mscgen_js-svg-__svg{font-family:Helvetica,sans-serif;font-size:12px;font-weight:normal;font-style:normal;text-decoration:none;background-color:white;stroke:black;stroke-width:2;color:black}.mscgen_js-svg-__svg path, .mscgen_js-svg-__svg rect{fill:none;color:black;stroke:black}.mscgen_js-svg-__svg .label-text-background{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg .bglayer{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg line{stroke:black}.mscgen_js-svg-__svg .return, .mscgen_js-svg-__svg .comment{stroke-dasharray:5,3}.mscgen_js-svg-__svg .inline_expression_divider{stroke-dasharray:10,5}.mscgen_js-svg-__svg text{color:inherit;stroke:none;text-anchor:middle}.mscgen_js-svg-__svg text.entity-text{text-decoration:underline}.mscgen_js-svg-__svg text.anchor-start{text-anchor:start}.mscgen_js-svg-__svg .arrow-marker{overflow:visible}.mscgen_js-svg-__svg .arrow-style{stroke-width:1}.mscgen_js-svg-__svg .arcrow, .mscgen_js-svg-__svg .arcrowomit, .mscgen_js-svg-__svg .emphasised{stroke-linecap:butt}.mscgen_js-svg-__svg .arcrowomit{stroke-dasharray:2,2;}.mscgen_js-svg-__svg .box, .mscgen_js-svg-__svg .entity{fill:white;stroke-linejoin:round}.mscgen_js-svg-__svg .inherit{stroke:inherit;color:inherit}.mscgen_js-svg-__svg .inherit-fill{fill:inherit}.mscgen_js-svg-__svg .watermark{stroke:black;color:black;fill:black;font-size:48pt;font-weight:bold;opacity:0.14}</style><marker orient="auto" id="mscgen_js-svg-__svgmethod-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-green" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="green" fill="green"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-green" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="green" fill="green"></polygon></marker></defs><g id="mscgen_js-svg-__svg__body" transform="translate(53,3) scale(1,1)"><g id="mscgen_js-svg-__svg__background"><rect width="976" height="310" x="-53" y="-3" class="bglayer"></rect></g><g id="mscgen_js-svg-__svg__arcspanlayer"></g><g id="mscgen_js-svg-__svg__lifelinelayer"><line x1="75" y1="38" x2="75" y2="76" class="arcrow"></line><line x1="315" y1="38" x2="315" y2="76" class="arcrow"></line><line x1="555" y1="38" x2="555" y2="76" class="arcrow"></line><line x1="795" y1="38" x2="795" y2="76" class="arcrow"></line><line x1="75" y1="76" x2="75" y2="114" class="arcrow"></line><line x1="315" y1="76" x2="315" y2="114" class="arcrow"></line><line x1="555" y1="76" x2="555" y2="114" class="arcrow"></line><line x1="795" y1="76" x2="795" y2="114" class="arcrow"></line><line x1="75" y1="114" x2="75" y2="152" class="arcrow"></line><line x1="315" y1="114" x2="315" y2="152" class="arcrow"></line><line x1="555" y1="114" x2="555" y2="152" class="arcrow"></line><line x1="795" y1="114" x2="795" y2="152" class="arcrow"></line><line x1="75" y1="152" x2="75" y2="190" class="arcrow"></line><line x1="315" y1="152" x2="315" y2="190" class="arcrow"></line><line x1="555" y1="152" x2="555" y2="190" class="arcrow"></line><line x1="795" y1="152" x2="795" y2="190" class="arcrow"></line><line x1="75" y1="190" x2="75" y2="228" class="arcrow"></line><line x1="315" y1="190" x2="315" y2="228" class="arcrow"></line><line x1="555" y1="190" x2="555" y2="228" class="arcrow"></line><line x1="795" y1="190" x2="795" y2="228" class="arcrow"></line><line x1="75" y1="228" x2="75" y2="266" class="arcrow"></line><line x1="315" y1="228" x2="315" y2="266" class="arcrow"></line><line x1="555" y1="228" x2="555" y2="266" class="arcrow"></line><line x1="795" y1="228" x2="795" y2="266" class="arcrow"></line><line x1="75" y1="266" x2="75" y2="304" class="arcrow"></line><line x1="315" y1="266" x2="315" y2="304" class="arcrow"></line><line x1="555" y1="266" x2="555" y2="304" class="arcrow"></line><line x1="795" y1="266" x2="795" y2="304" class="arcrow"></line></g><g id="mscgen_js-svg-__svg__sequencelayer"><g id="mscgen_js-svg-__svgentities"><g><rect width="150" height="38" class="entity" style="fill:lime;"></rect><g><text x="75" y="22.5" class="entity-text "><tspan>Client</tspan></text></g></g><g><rect width="150" height="38" x="240" class="entity" style="fill:cyan;"></rect><g><text x="315" y="22.5" class="entity-text "><tspan>Rails</tspan></text></g></g><g><rect width="150" height="38" x="480" class="entity" style="fill:orange;"></rect><g><text x="555" y="22.5" class="entity-text "><tspan>EtagCaching</tspan></text></g></g><g><rect width="150" height="38" x="720" class="entity" style="fill:white;"></rect><g><text x="795" y="22.5" class="entity-text "><tspan>Redis</tspan></text></g></g></g><g><line x1="75" y1="95" x2="315" y2="95" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="127.97" y="79.5" class="label-text-background"></rect><text x="195" y="90.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="133" x2="555" y2="133" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="117.5" class="label-text-background"></rect><text x="435" y="128.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="555" y1="171" x2="795" y2="171" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="135.64" height="14" x="607.17" y="155.5" class="label-text-background"></rect><text x="675" y="166.5" class="directional-text method-text "><tspan>read(key = 'GET <Etag>')</tspan></text></g></g><g><line x1="795" y1="209" x2="555" y2="209" class="arc directional method" style="stroke:green" marker-end="url(#mscgen_js-svg-__svgmethod-green)"></line><g><rect width="48.02" height="14" x="650.98" y="193.5" class="label-text-background"></rect><text x="675" y="204.5" class="directional-text method-text " style="fill:green;"><tspan>cache hit</tspan></text></g></g><g></g><g><line x1="555" y1="285" x2="75" y2="285" class="arc directional method" style="stroke:blue" marker-end="url(#mscgen_js-svg-__svgmethod-blue)"></line><g><rect width="90.72" height="14" x="269.63" y="269.5" class="label-text-background"></rect><text x="315" y="280.5" class="directional-text method-text " style="fill:blue;"><tspan>304 Not Modified</tspan></text></g></g></g><g id="mscgen_js-svg-__svg__notelayer"></g><g id="mscgen_js-svg-__svg__watermark"></g></g></svg>
\ No newline at end of file diff --git a/doc/development/img/cache-miss.svg b/doc/development/img/cache-miss.svg new file mode 100644 index 00000000000..8429e6a1918 --- /dev/null +++ b/doc/development/img/cache-miss.svg @@ -0,0 +1,24 @@ +<svg version="1.1" id="mscgen_js-svg-__svg" class="mscgen_js-svg-__svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="976" height="386" viewBox="0 0 976 386"><desc> + +# Generated by mscgen_js - https://sverweij.github.io/mscgen_js +msc { + # options + hscale="1.5"; + + # entities + c [label="Client", textbgcolor="lime"], + rails [label="Rails", textbgcolor="cyan"], + etag [label="EtagCaching", textbgcolor="orange"], + redis [label="Redis", textbgcolor="white"]; + + # arcs + c => rails [label="GET /projects/5/pipelines"]; + rails => etag [label="GET /projects/5/pipelines"]; + etag => redis [label="read(key = 'GET <Etag>')"]; + redis => etag [label="cache miss", linecolor="red", textcolor="red"]; + |||; + etag => redis [label="write('<New Etag>')"]; + etag => rails [label="GET /projects/5/pipelines"]; + rails => c [label="JSON response w/ ETag", linecolor="blue", textcolor="blue"]; +} +</desc><defs><style type="text/css">svg.mscgen_js-svg-__svg{font-family:Helvetica,sans-serif;font-size:12px;font-weight:normal;font-style:normal;text-decoration:none;background-color:white;stroke:black;stroke-width:2}.mscgen_js-svg-__svg path, .mscgen_js-svg-__svg rect{fill:none}.mscgen_js-svg-__svg .label-text-background{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg .bglayer{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg line{}.mscgen_js-svg-__svg .return, .mscgen_js-svg-__svg .comment{stroke-dasharray:5,3}.mscgen_js-svg-__svg .inline_expression_divider{stroke-dasharray:10,5}.mscgen_js-svg-__svg text{color:inherit;stroke:none;text-anchor:middle}.mscgen_js-svg-__svg text.entity-text{text-decoration:underline}.mscgen_js-svg-__svg text.anchor-start{text-anchor:start}.mscgen_js-svg-__svg .arrow-marker{overflow:visible}.mscgen_js-svg-__svg .arrow-style{stroke-width:1}.mscgen_js-svg-__svg .arcrow, .mscgen_js-svg-__svg .arcrowomit, .mscgen_js-svg-__svg .emphasised{stroke-linecap:butt}.mscgen_js-svg-__svg .arcrowomit{stroke-dasharray:2,2}.mscgen_js-svg-__svg .box, .mscgen_js-svg-__svg .entity{fill:white;stroke-linejoin:round}.mscgen_js-svg-__svg .inherit{stroke:inherit;color:inherit}.mscgen_js-svg-__svg .inherit-fill{fill:inherit}.mscgen_js-svg-__svg .watermark{font-size:48pt;font-weight:bold;opacity:0.14}</style><marker orient="auto" id="mscgen_js-svg-__svgmethod-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-red" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="red" fill="red"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-red" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="red" fill="red"></polygon></marker></defs><g id="mscgen_js-svg-__svg__body" transform="translate(53,3) scale(1,1)"><g id="mscgen_js-svg-__svg__background"><rect width="976" height="386" x="-53" y="-3" class="bglayer"></rect></g><g id="mscgen_js-svg-__svg__arcspanlayer"></g><g id="mscgen_js-svg-__svg__lifelinelayer"><line x1="75" y1="38" x2="75" y2="76" class="arcrow"></line><line x1="315" y1="38" x2="315" y2="76" class="arcrow"></line><line x1="555" y1="38" x2="555" y2="76" class="arcrow"></line><line x1="795" y1="38" x2="795" y2="76" class="arcrow"></line><line x1="75" y1="76" x2="75" y2="114" class="arcrow"></line><line x1="315" y1="76" x2="315" y2="114" class="arcrow"></line><line x1="555" y1="76" x2="555" y2="114" class="arcrow"></line><line x1="795" y1="76" x2="795" y2="114" class="arcrow"></line><line x1="75" y1="114" x2="75" y2="152" class="arcrow"></line><line x1="315" y1="114" x2="315" y2="152" class="arcrow"></line><line x1="555" y1="114" x2="555" y2="152" class="arcrow"></line><line x1="795" y1="114" x2="795" y2="152" class="arcrow"></line><line x1="75" y1="152" x2="75" y2="190" class="arcrow"></line><line x1="315" y1="152" x2="315" y2="190" class="arcrow"></line><line x1="555" y1="152" x2="555" y2="190" class="arcrow"></line><line x1="795" y1="152" x2="795" y2="190" class="arcrow"></line><line x1="75" y1="190" x2="75" y2="228" class="arcrow"></line><line x1="315" y1="190" x2="315" y2="228" class="arcrow"></line><line x1="555" y1="190" x2="555" y2="228" class="arcrow"></line><line x1="795" y1="190" x2="795" y2="228" class="arcrow"></line><line x1="75" y1="228" x2="75" y2="266" class="arcrow"></line><line x1="315" y1="228" x2="315" y2="266" class="arcrow"></line><line x1="555" y1="228" x2="555" y2="266" class="arcrow"></line><line x1="795" y1="228" x2="795" y2="266" class="arcrow"></line><line x1="75" y1="266" x2="75" y2="304" class="arcrow"></line><line x1="315" y1="266" x2="315" y2="304" class="arcrow"></line><line x1="555" y1="266" x2="555" y2="304" class="arcrow"></line><line x1="795" y1="266" x2="795" y2="304" class="arcrow"></line><line x1="75" y1="304" x2="75" y2="342" class="arcrow"></line><line x1="315" y1="304" x2="315" y2="342" class="arcrow"></line><line x1="555" y1="304" x2="555" y2="342" class="arcrow"></line><line x1="795" y1="304" x2="795" y2="342" class="arcrow"></line><line x1="75" y1="342" x2="75" y2="380" class="arcrow"></line><line x1="315" y1="342" x2="315" y2="380" class="arcrow"></line><line x1="555" y1="342" x2="555" y2="380" class="arcrow"></line><line x1="795" y1="342" x2="795" y2="380" class="arcrow"></line></g><g id="mscgen_js-svg-__svg__sequencelayer"><g id="mscgen_js-svg-__svgentities"><g><rect width="150" height="38" class="entity" style="fill:lime;"></rect><g><text x="75" y="22.5" class="entity-text "><tspan>Client</tspan></text></g></g><g><rect width="150" height="38" x="240" class="entity" style="fill:cyan;"></rect><g><text x="315" y="22.5" class="entity-text "><tspan>Rails</tspan></text></g></g><g><rect width="150" height="38" x="480" class="entity" style="fill:orange;"></rect><g><text x="555" y="22.5" class="entity-text "><tspan>EtagCaching</tspan></text></g></g><g><rect width="150" height="38" x="720" class="entity" style="fill:white;"></rect><g><text x="795" y="22.5" class="entity-text "><tspan>Redis</tspan></text></g></g></g><g><line x1="75" y1="95" x2="315" y2="95" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="127.97" y="79.5" class="label-text-background"></rect><text x="195" y="90.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="133" x2="555" y2="133" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="117.5" class="label-text-background"></rect><text x="435" y="128.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="555" y1="171" x2="795" y2="171" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="135.64" height="14" x="607.17" y="155.5" class="label-text-background"></rect><text x="675" y="166.5" class="directional-text method-text "><tspan>read(key = 'GET <Etag>')</tspan></text></g></g><g><line x1="795" y1="209" x2="555" y2="209" class="arc directional method" style="stroke:red" marker-end="url(#mscgen_js-svg-__svgmethod-red)"></line><g><rect width="60.02" height="14" x="644.98" y="193.5" class="label-text-background"></rect><text x="675" y="204.5" class="directional-text method-text " style="fill:red;"><tspan>cache miss</tspan></text></g></g><g></g><g><line x1="555" y1="285" x2="795" y2="285" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="103.94" height="14" x="623.02" y="269.5" class="label-text-background"></rect><text x="675" y="280.5" class="directional-text method-text "><tspan>write('<New Etag>')</tspan></text></g></g><g><line x1="555" y1="323" x2="315" y2="323" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="307.5" class="label-text-background"></rect><text x="435" y="318.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="361" x2="75" y2="361" class="arc directional method" style="stroke:blue" marker-end="url(#mscgen_js-svg-__svgmethod-blue)"></line><g><rect width="130.72" height="14" x="129.63" y="345.5" class="label-text-background"></rect><text x="195" y="356.5" class="directional-text method-text " style="fill:blue;"><tspan>JSON response w/ ETag</tspan></text></g></g></g><g id="mscgen_js-svg-__svg__notelayer"></g><g id="mscgen_js-svg-__svg__watermark"></g></g></svg>
\ No newline at end of file diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index fd8335d251e..587922d0136 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -58,10 +58,22 @@ migration was tested. ## Removing indices -If you need to remove index, please add a condition like in following example: +When removing an index make sure to use the method `remove_concurrent_index` instead +of the regular `remove_index` method. The `remove_concurrent_index` method +automatically drops concurrent indexes when using PostgreSQL, removing the +need for downtime. To use this method you must disable transactions by calling +the method `disable_ddl_transaction!` in the body of your migration class like +so: ```ruby -remove_index :namespaces, column: :name if index_exists?(:namespaces, :name) +class MyMigration < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + disable_ddl_transaction! + + def up + remove_concurrent_index :table_name, :column_name if index_exists?(:table_name, :column_name) + end +end ``` ## Adding indices diff --git a/doc/development/polling.md b/doc/development/polling.md index a7f2962acf0..05e19f0c515 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.md @@ -22,6 +22,14 @@ Instead you should use polling mechanism with ETag caching in Redis. ## How it works +Cache Miss: + + + +Cache Hit: + + + 1. Whenever a resource changes we generate a random value and store it in Redis. 1. When a client makes a request we set the `ETag` response header to the value @@ -36,6 +44,12 @@ Instead you should use polling mechanism with ETag caching in Redis. 1. If the `If-None-Match` header does not match the current value in Redis we have to generate a new response, because the resource changed. +Do not use query parameters (for example `?scope=all`) for endpoints where you +want to enable ETag caching. The middleware takes into account only the request +path and ignores query parameters. All parameters should be included in the +request path. By doing this we avoid query parameter ordering problems and make +route matching easier. + For more information see: - [RFC 7232](https://tools.ietf.org/html/rfc7232) - [ETag proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/26926) diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md new file mode 100644 index 00000000000..482ec54207b --- /dev/null +++ b/doc/development/writing_documentation.md @@ -0,0 +1,72 @@ +# Writing documentation + + - **General Documentation**: written by the developers responsible by creating features. Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers. + - **Technical Articles**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/). + - **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs, in the same merge request containing code. + +## Distinction between General Documentation and Technical Articles + +### General documentation + +General documentation is categorized by _User_, _Admin_, and _Contributor_, and describe what that feature is, what it does, and its available settings. + +### Technical Articles + +Technical articles replace technical content that once lived in the [GitLab Blog](https://about.gitlab.com/blog/), where they got out-of-date and weren't easily found. + +They are topic-related documentation, written with an user-friendly approach and language, aiming to provide the community with guidance on specific processes to achieve certain objectives. + +A technical article guides users and/or admins to achieve certain objectives (within guides and tutorials), or provide an overview of that particular topic or feature (within technical overviews). It can also describe the use, implementation, or integration of third-party tools with GitLab. + +They live under `doc/topics/topic-name/`, and can be searched per topic, within "Indexes per Topic" pages. The topics are listed on the main [Indexes per Topic](../topics/index.md) page. + +#### Types of Technical Articles + +- **User guides**: technical content to guide regular users from point A to point B +- **Admin guides**: technical content to guide administrators of GitLab instances from point A to point B +- **Technical Overviews**: technical content describing features, solutions, and third-party integrations +- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach very specific objectives + +#### Understanding guides, tutorials, and technical overviews + +Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 > 3 > 4 > 5 (B)`. + +A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them. + +- Live example: "GitLab Pages from A to Z - [Part 1](../user/project/pages/getting_started_part_one.md) to [Part 4](../user/project/pages/getting_started_part_four.md)" + +A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B. +It does not only describes steps 2 and 3, but also shows you how to accomplish them. + +- Live example (on the blog): [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) + +A **technical overview** is a description of what a certain feature is, and what it does, but does not walk +through the process of how to use it systematically. + +- Live example (on the blog): [GitLab Workflow, an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/) + +#### Special format + +Every **Technical Article** contains, in the very beginning, a blockquote with the following information: + +- A reference to the **type of article** (user guide, admin guide, tech overview, tutorial) +- A reference to the **knowledge level** expected from the reader to be able to follow through (beginner, intermediate, advanced) +- A reference to the **author's name** and **GitLab.com handle** + +```md +> **Type:** tutorial || +> **Level:** intermediary || +> **Author:** [Name Surname](https://gitlab.com/username) +``` + +#### Technical Articles - Writing Method + +Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team. + +## Documentation style guidelines + +All the docs follow the same [styleguide](doc_styleguide.md). + +### Markdown + +Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future. diff --git a/doc/install/installation.md b/doc/install/installation.md index a6b10176450..5b72c2cce07 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -459,9 +459,9 @@ Make GitLab start on boot: ### Install Gitaly -As of GitLab 9.0 Gitaly is an **optional** component. Its -configuration is expected to change in GitLab 9.1. It is OK to wait -with setting up Gitaly until you upgrade to GitLab 9.1 or later. +As of GitLab 9.1 Gitaly is an **optional** component. Its +configuration is still changing regularly. It is OK to wait +with setting up Gitaly until you upgrade to GitLab 9.2 or later. # Fetch Gitaly source with Git and compile with Go sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly]" RAILS_ENV=production @@ -471,18 +471,20 @@ with setting up Gitaly until you upgrade to GitLab 9.1 or later. sudo chown git /home/git/gitlab/tmp/sockets/private # Configure Gitaly - echo 'GITALY_SOCKET_PATH=/home/git/gitlab/tmp/sockets/private/gitaly.socket' | \ - sudo -u git tee -a /home/git/gitaly/env - + cd /home/git/gitaly + sudo -u git cp config.toml.example config.toml + # If you are using non-default settings you need to update config.toml + sudo -u git -H editor config.toml + # Enable Gitaly in the init script echo 'gitaly_enabled=true' | sudo tee -a /etc/default/gitlab -Next, edit `/home/git/gitlab/config/gitlab.yml` and make sure `socket_path` in +Next, edit `/home/git/gitlab/config/gitlab.yml` and make sure `enabled: true` in the `gitaly:` section is uncommented. # <- gitlab.yml indentation starts here gitaly: - socket_path: tmp/sockets/private/gitaly.socket + enabled: true For more information about configuring Gitaly see [doc/administration/gitaly](../administration/gitaly). diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 7b586138f42..35586091f74 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -129,6 +129,9 @@ If you want to run the database separately, expect a size of about 1 MB per user ### PostgreSQL Requirements +As of GitLab 9.0, PostgreSQL 9.6 is recommended. Lower versions of PostgreSQL +may work but primary testing and developement takes place using PostgreSQL 9.6. + Users using PostgreSQL must ensure the `pg_trgm` extension is loaded into every GitLab database. This extension can be enabled (using a PostgreSQL super user) by running the following query for every database: diff --git a/doc/profile/README.md b/doc/profile/README.md index 54e44d65959..aed64ac1228 100644 --- a/doc/profile/README.md +++ b/doc/profile/README.md @@ -2,3 +2,4 @@ - [Preferences](../user/profile/preferences.md) - [Two-factor Authentication (2FA)](../user/profile/account/two_factor_authentication.md) +- [Deleting your account](../user/profile/account/delete_account.md) diff --git a/doc/security/img/two_factor_authentication_group_settings.png b/doc/security/img/two_factor_authentication_group_settings.png Binary files differnew file mode 100644 index 00000000000..a1b3c58bfdc --- /dev/null +++ b/doc/security/img/two_factor_authentication_group_settings.png diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index c8499380c18..f02f7b807cf 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -8,7 +8,7 @@ their phone. You can read more about it here: [Two-factor Authentication (2FA)](../profile/two_factor_authentication.md) -## Enabling 2FA +## Enforcing 2FA for all users Users on GitLab, can enable it without any admin's intervention. If you want to enforce everyone to setup 2FA, you can choose from two different ways: @@ -28,6 +28,21 @@ period to `0`. --- +## Enforcing 2FA for all users in a group + +If you want to enforce 2FA only for certain groups, you can enable it in the +group settings and specify a grace period as above. To change this setting you +need to be administrator or owner of the group. + +If there are multiple 2FA requirements (i.e. group + all users, or multiple +groups) the shortest grace period will be used. + +--- + + + +--- + ## Disabling 2FA for everyone There may be some special situations where you want to disable 2FA for everyone diff --git a/doc/topics/index.md b/doc/topics/index.md new file mode 100644 index 00000000000..6de13d79554 --- /dev/null +++ b/doc/topics/index.md @@ -0,0 +1,16 @@ +# Topics + +Welcome to Topics! We have organized our content resources into topics +to get you started on areas of your interest. Each topic page +consists of an index listing all related content. It will guide +you through better understanding GitLab's concepts +through our regular docs, and, when available, through articles (guides, +tutorials, technical overviews, blog posts) and videos. + +- [GitLab Installation](../install/README.md) +- [Continuous Integration (GitLab CI)](../ci/README.md) +- [GitLab Pages](../user/project/pages/index.md) + +>**Note:** +Non-linked topics are currently under development and subjected to change. +More topics will be available soon. diff --git a/doc/update/8.2-to-8.3.md b/doc/update/8.2-to-8.3.md index f28896c2227..4b3c5bf6d64 100644 --- a/doc/update/8.2-to-8.3.md +++ b/doc/update/8.2-to-8.3.md @@ -120,6 +120,14 @@ There are new configuration options available for [`gitlab.yml`][yaml]. View the git diff origin/8-2-stable:config/gitlab.yml.example origin/8-3-stable:config/gitlab.yml.example ``` +#### GitLab default file + +The value of the `gitlab_workhorse_options` variable should be updated within the default gitlab file (`/etc/default/gitlab`) according to the following diff: + +```sh +git diff origin/8-2-stable:lib/support/init.d/gitlab.default.example origin/8-3-stable:lib/support/init.d/gitlab.default.example +``` + #### Nginx configuration GitLab 8.3 introduces major changes in the NGINX configuration. diff --git a/doc/update/9.0-to-9.1.md b/doc/update/9.0-to-9.1.md new file mode 100644 index 00000000000..ae983dea384 --- /dev/null +++ b/doc/update/9.0-to-9.1.md @@ -0,0 +1,383 @@ +# From 9.0 to 9.1 + +** TODO: ** + +# TODO clean out 9.0-specific stuff + +Make sure you view this update guide from the tag (version) of GitLab you would +like to install. In most cases this should be the highest numbered production +tag (without rc in it). You can select the tag in the version dropdown at the +top left corner of GitLab (below the menu bar). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be +sure to upgrade your interpreter if necessary. + +You can check which version you are running with `ruby -v`. + +Download and compile Ruby: + +```bash +mkdir /tmp/ruby && cd /tmp/ruby +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz +echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz +cd ruby-2.3.3 +./configure --disable-install-rdoc +make +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-ri --no-rdoc +``` + +### 4. Update Node + +GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and +it has a minimum requirement of node v4.3.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v4.3.0` you will need to update to a newer version. You +can find instructions to install from community maintained packages or compile +from source at the nodejs.org website. + +<https://nodejs.org/en/download/> + + +Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage +JavaScript dependencies. + +```bash +curl --location https://yarnpkg.com/install.sh | bash - +``` + +More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). + +### 5. Get latest code + +```bash +cd /home/git/gitlab + +sudo -u git -H git fetch --all +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +``` + +For GitLab Community Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 9-1-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 9-1-stable-ee +``` + +### 6. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +sudo -u git -H git fetch --all --tags +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +``` + +### 7. Update gitlab-workhorse + +Install and compile gitlab-workhorse. This requires +[Go 1.5](https://golang.org/dl) which should already be on your system from +GitLab 8.1. GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-workhorse + +sudo -u git -H git fetch --all --tags +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) +sudo -u git -H make +``` + +### 8. Update configuration files + +#### New configuration options for `gitlab.yml` + +There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +cd /home/git/gitlab + +git diff origin/9-0-stable:config/gitlab.yml.example origin/9-1-stable:config/gitlab.yml.example +``` + +#### Configuration changes for repository storages + +This version introduces a new configuration structure for repository storages. +Update your current configuration as follows, replacing with your storages names and paths: + +**For installations from source** + +1. Update your `gitlab.yml`, from + + ```yaml + repositories: + storages: # You must have at least a 'default' storage path. + default: /home/git/repositories + nfs: /mnt/nfs/repositories + cephfs: /mnt/cephfs/repositories + ``` + + to + + ```yaml + repositories: + storages: # You must have at least a 'default' storage path. + default: + path: /home/git/repositories + nfs: + path: /mnt/nfs/repositories + cephfs: + path: /mnt/cephfs/repositories + ``` + +**For Omnibus installations** + +1. Update your `/etc/gitlab/gitlab.rb`, from + + ```ruby + git_data_dirs({ + "default" => "/var/opt/gitlab/git-data", + "nfs" => "/mnt/nfs/git-data", + "cephfs" => "/mnt/cephfs/git-data" + }) + ``` + + to + + ```ruby + git_data_dirs({ + "default" => { "path" => "/var/opt/gitlab/git-data" }, + "nfs" => { "path" => "/mnt/nfs/git-data" }, + "cephfs" => { "path" => "/mnt/cephfs/git-data" } + }) + ``` + +#### Git configuration + +Configure Git to generate packfile bitmaps (introduced in Git 2.0) on +the GitLab server during `git gc`. + +```sh +cd /home/git/gitlab + +sudo -u git -H git config --global repack.writeBitmaps true +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/9-0-stable:lib/support/nginx/gitlab-ssl origin/9-1-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/9-0-stable:lib/support/nginx/gitlab origin/9-1-stable:lib/support/nginx/gitlab +``` + +If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx +configuration as GitLab application no longer handles setting it. + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-1-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-0-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### Init script + +There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/9-0-stable:lib/support/init.d/gitlab.default.example origin/9-1-stable:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 9. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Update node dependencies and recompile assets +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production + +# Clean up cache +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production +``` + +**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). + +### 10. Optional: install Gitaly + +Gitaly is still an optional component of GitLab. If you want to save time +during your 9.1 upgrade **you can skip this step**. + +If you have not yet set up Gitaly then follow [Gitaly section of the installation +guide](../install/installation.md#install-gitaly). + +If you installed Gitaly in GitLab 9.0 you need to make some changes in +gitlab.yml, and create a new config.toml file. + +#### Gitaly gitlab.yml changes + +Look for `socket_path:` the `gitaly:` section. Its value is usually +`/home/git/gitlab/tmp/sockets/private/gitaly.socket`. Note what socket +path your gitlab.yml is using. Now go to the `repositories:` section, +and for each entry under `storages:`, add a `gitaly_address:` based on +the socket path, but with `unix:` in front. + +```yaml + repositories: + storages: + default: + path: /home/git/repositories + gitaly_address: unix:/home/git/gitlab/tmp/sockets/private/gitaly.socket + other_storage: + path: /home/git/other-repositories + gitaly_address: unix:/home/git/gitlab/tmp/sockets/private/gitaly.socket +``` + +Each entry under `storages:` should use the same `gitaly_address`. + +#### Gitaly config.toml + +In GitLab 9.1 we are replacing environment variables in Gitaly with a +TOML configuration file. + +```shell +cd /home/git/gitaly + +sudo mv env env.old +sudo -u git cp config.toml.example config.toml +# If you are using custom repository storage paths they need to be in config.toml +sudo -u git -H editor config.toml +``` + +### 11. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 12. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (9.0) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 8.17 to 9.0](8.17-to-9.0.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. + +[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-1-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-1-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index 154a0f817da..1c493599cf8 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -57,7 +57,7 @@ sudo -u git -H bundle clean sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production # Clean up assets and cache -sudo -u git -H bundle exec rake gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production ``` ### 4. Update gitlab-workhorse to the corresponding version diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md new file mode 100644 index 00000000000..505248536c8 --- /dev/null +++ b/doc/user/profile/account/delete_account.md @@ -0,0 +1,25 @@ +# Deleting a User Account + +- As a user, you can delete your own account by navigating to **Settings** > **Account** and selecting **Delete account** +- As an admin, you can delete a user account by navigating to the **Admin Area**, selecting the **Users** tab, selecting a user, and clicking on **Remvoe user** + +## Associated Records + +> Introduced for issues in [GitLab 9.0][ce-7393], and for merge requests, award emoji, notes, and abuse reports in [GitLab 9.1][ce-10467]. + +When a user account is deleted, not all associated records are deleted with it. Here's a list of things that will not be deleted: + +- Issues that the user created +- Merge requests that the user created +- Notes that the user created +- Abuse reports that the user reported +- Award emoji that the user craeted + + +Instead of being deleted, these records will be moved to a system-wide "Ghost User", whose sole purpose is to act as a container for such records. + + +[ce-7393]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7393 +[ce-10467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467 + + diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index b6221620e58..6a2ca7fb428 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -10,6 +10,7 @@ - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need to pass a personal access token instead of your password in order to login to GitLab's Container Registry. +- Multiple level image names support was added in GitLab 9.1 With the Docker Container Registry integrated into GitLab, every project can have its own space to store its Docker images. @@ -54,18 +55,25 @@ sure that you are using the Registry URL with the namespace and project name that is hosted on GitLab: ``` -docker build -t registry.example.com/group/project . -docker push registry.example.com/group/project +docker build -t registry.example.com/group/project/image . +docker push registry.example.com/group/project/image ``` Your image will be named after the following scheme: ``` -<registry URL>/<namespace>/<project> +<registry URL>/<namespace>/<project>/<image> ``` -As such, the name of the image is unique, but you can differentiate the images -using tags. +GitLab supports up to three levels of image repository names. + +Following examples of image tags are valid: + +``` +registry.example.com/group/project:some-tag +registry.example.com/group/project/image:latest +registry.example.com/group/project/my/image:rc1 +``` ## Use images from GitLab Container Registry @@ -73,7 +81,7 @@ To download and run a container from images hosted in GitLab Container Registry, use `docker run`: ``` -docker run [options] registry.example.com/group/project [arguments] +docker run [options] registry.example.com/group/project/image [arguments] ``` For more information on running Docker containers, visit the @@ -136,7 +144,7 @@ A user attempted to enable an S3-backed Registry. The `docker login` step went fine. However, when pushing an image, the output showed: ``` -The push refers to a repository [s3-testing.myregistry.com:4567/root/docker-test] +The push refers to a repository [s3-testing.myregistry.com:4567/root/docker-test/docker-image] dc5e59c14160: Pushing [==================================================>] 14.85 kB 03c20c1a019a: Pushing [==================================================>] 2.048 kB a08f14ef632e: Pushing [==================================================>] 2.048 kB @@ -229,7 +237,7 @@ a container image. You may need to run as root to do this. For example: ```sh docker login s3-testing.myregistry.com:4567 -docker push s3-testing.myregistry.com:4567/root/docker-test +docker push s3-testing.myregistry.com:4567/root/docker-test/docker-image ``` In the example above, we see the following trace on the mitmproxy window: diff --git a/doc/user/project/integrations/img/jira_project_settings.png b/doc/user/project/integrations/img/jira_project_settings.png Binary files differnew file mode 100644 index 00000000000..cb6a6ba14ce --- /dev/null +++ b/doc/user/project/integrations/img/jira_project_settings.png diff --git a/doc/user/project/integrations/img/microsoft_teams_configuration.png b/doc/user/project/integrations/img/microsoft_teams_configuration.png Binary files differnew file mode 100644 index 00000000000..b5c9efc3dd9 --- /dev/null +++ b/doc/user/project/integrations/img/microsoft_teams_configuration.png diff --git a/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png b/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png Binary files differindex 1f5a44f8820..214b10624a9 100644 --- a/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png +++ b/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 4c64d1e0907..e02f81fd972 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -157,6 +157,11 @@ the same goal: where `PROJECT-1` is the issue ID of the JIRA project. +>**Note:** +- Only commits and merges into the project's default branch (usually **master**) will + close an issue in Jira. You can change your projects default branch under + [project settings](img/jira_project_settings.png). + ### JIRA issue closing example Let's consider the following example: diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md new file mode 100644 index 00000000000..fbf9c1de443 --- /dev/null +++ b/doc/user/project/integrations/microsoft_teams.md @@ -0,0 +1,33 @@ +# Microsoft Teams Service + +## On Microsoft Teams + +To enable Microsoft Teams integration you must create an incoming webhook integration on Microsoft Teams by following the steps described in this [document](https://msdn.microsoft.com/en-us/microsoft-teams/connectors) + +## On GitLab + +After you set up Microsoft Teams, it's time to set up GitLab. + +Navigate to the [Integrations page](project_services.md#accessing-the-project-services) +and select the **Microsoft Teams Notification** service to configure it. +There, you will see a checkbox with the following events that can be triggered: + +- Push +- Issue +- Confidential issue +- Merge request +- Note +- Tag push +- Pipeline +- Wiki page + +At the end fill in your Microsoft Teams details: + +| Field | Description | +| ----- | ----------- | +| **Webhook** | The incoming webhook URL which you have to setup on Microsoft Teams. | +| **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | + +After you are all done, click **Save changes** for the changes to take effect. + +
\ No newline at end of file diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 12d7700176c..a74014b6b2f 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -160,23 +160,19 @@ The queries utilized by GitLab are shown in the following table. Once configured, GitLab will attempt to retrieve performance metrics for any environment which has had a successful deployment. If monitoring data was -successfully retrieved, a metrics button will appear on the environment's +successfully retrieved, a Monitoring button will appear on the environment's detail page.  -Clicking on the metrics button will display a new page, showing up to the last +Clicking on the Monitoring button will display a new page, showing up to the last 8 hours of performance data. It may take a minute or two for data to appear after initial deployment. ## Troubleshooting -If the metrics button is not appearing, then one of a few issues may be -occurring: +If the "Attempting to load performance data" screen continues to appear, it could be due to: -- GitLab is not able to reach the Prometheus server. A test request can be sent - to the Prometheus server from the [Prometheus Service](#configuration-in-gitlab) - configuration screen. - No successful deployments have occurred to this environment. - Prometheus does not have performance data for this environment, or the metrics are not labeled correctly. To test this, connect to the Prometheus server and diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 55610a7b014..f846736028f 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -141,6 +141,7 @@ with GitLab 8.12. With the new job permissions model, there is now an easy way to access all dependent source code in a project. That way, we can: +1. Access a project's dependent repositories 1. Access a project's [Git submodules][gitsub] 1. Access private container images 1. Access project's and submodule LFS objects @@ -177,6 +178,22 @@ As a user: access to. As an Administrator, you can verify that by impersonating the user and retry the failing job in order to verify that everything is correct. +### Dependent repositories + +The [Job environment variable][jobenv] `CI_JOB_TOKEN` can be used to +authenticate any clones of dependent repositories. For example: + +``` +git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/myuser/mydependentrepo +``` + +It can also be used for system-wide authentication +(only do this in a docker container, it will overwrite ~/.netrc): + +``` +echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc +``` + ### Git submodules To properly configure submodules with GitLab CI, read the @@ -221,3 +238,4 @@ test: [triggers]: ../../ci/triggers/README.md [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update [workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse +[jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index 35af48724f2..50767095aa0 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -1,5 +1,9 @@ # GitLab Pages from A to Z: Part 4 +> **Type**: user guide || +> **Level**: intermediate || +> **Author**: [Marcia Ramos](https://gitlab.com/marcia) + - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) - [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md) diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 582a4afbab4..e92549aa0df 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,5 +1,9 @@ # GitLab Pages from A to Z: Part 1 +> **Type**: user guide || +> **Level**: beginner || +> **Author**: [Marcia Ramos](https://gitlab.com/marcia) + - **Part 1: Static sites and GitLab Pages domains** - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) - [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md) diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 55fcd5f00f2..80f16e43e20 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,5 +1,9 @@ # GitLab Pages from A to Z: Part 3 +> **Type**: user guide || +> **Level**: beginner || +> **Author**: [Marcia Ramos](https://gitlab.com/marcia) + - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) - **Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates** diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index d0e2c467fee..578ad13f5df 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -1,5 +1,9 @@ # GitLab Pages from A to Z: Part 2 +> **Type**: user guide || +> **Level**: beginner || +> **Author**: [Marcia Ramos](https://gitlab.com/marcia) + - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) - **Part 2: Quick start guide - Setting up GitLab Pages** - [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md) diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 4c52974e103..e91d36987a9 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -66,14 +66,13 @@ Below is the table of events users can be notified of: In all of the below cases, the notification will be sent to: - Participants: - the author and assignee of the issue/merge request - - the author of the pipeline - authors of comments on the issue/merge request - anyone mentioned by `@username` in the issue/merge request title or description - anyone mentioned by `@username` in any of the comments on the issue/merge request ...with notification level "Participating" or higher -- Watchers: users with notification level "Watch" (however successful pipeline would be off for watchers) +- Watchers: users with notification level "Watch" - Subscribers: anyone who manually subscribed to the issue/merge request - Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below @@ -89,8 +88,8 @@ In all of the below cases, the notification will be sent to: | Reopen merge request | | | Merge merge request | | | New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | -| Failed pipeline | The above, plus the author of the pipeline | -| Successful pipeline | The above, plus the author of the pipeline | +| Failed pipeline | The author of the pipeline | +| Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set | In addition, if the title or description of an Issue or Merge Request is |
