diff options
Diffstat (limited to 'doc')
38 files changed, 949 insertions, 520 deletions
diff --git a/doc/README.md b/doc/README.md index 03371226041..20fcd2e1724 100644 --- a/doc/README.md +++ b/doc/README.md @@ -165,6 +165,7 @@ configuration. Then customize everything from buildpacks to CI/CD. - [Deployment of Helm, Ingress, and Prometheus on Kubernetes](user/project/clusters/index.md#installing-applications) - [Protected variables](ci/variables/README.md#protected-variables) - [Easy creation of Kubernetes clusters on GKE](user/project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) +- [Executable Runbooks](user/project/clusters/runbooks/index.md) ### Monitor diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index 96803746637..481eb692674 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -61,7 +61,7 @@ on an Linux NFS server, do the following: 2. Restart the NFS server process. For example, on CentOS run `service nfs restart`. -## AWS Elastic File System +## Avoid using AWS's Elastic File System (EFS) GitLab strongly recommends against using AWS Elastic File System (EFS). Our support team will not be able to assist on performance issues related to @@ -78,6 +78,23 @@ stored on a local volume. For more details on another person's experience with EFS, see [Amazon's Elastic File System: Burst Credits](https://rawkode.com/2017/04/16/amazons-elastic-file-system-burst-credits/) +## Avoid using PostgreSQL with NFS + +GitLab strongly recommends against running your PostgreSQL database +across NFS. The GitLab support team will not be able to assist on performance issues related to +this configuration. + +Additionally, this configuration is specifically warned against in the +[Postgres Documentation](https://www.postgresql.org/docs/current/static/creating-cluster.html#CREATING-CLUSTER-NFS): + +>PostgreSQL does nothing special for NFS file systems, meaning it assumes NFS behaves exactly like +>locally-connected drives. If the client or server NFS implementation does not provide standard file +>system semantics, this can cause reliability problems. Specifically, delayed (asynchronous) writes +>to the NFS server can cause data corruption problems. + +For supported database architecture, please see our documentation on +[Configuring a Database for GitLab HA](https://docs.gitlab.com/ee/administration/high_availability/database.html). + ## NFS Client mount options Below is an example of an NFS mount point defined in `/etc/fstab` we use on diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index b5d1ff698c6..dcee57def74 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -15,7 +15,7 @@ Omnibus GitLab packages. > **Notes:** > - Redis requires authentication for High Availability. See -> [Redis Security](http://redis.io/topics/security) documentation for more +> [Redis Security](https://redis.io/topics/security) documentation for more > information. We recommend using a combination of a Redis password and tight > firewall rules to secure your Redis service. > - You are highly encouraged to read the [Redis Sentinel][sentinel] documentation @@ -82,7 +82,7 @@ When a **Master** fails to respond, it's the application's responsibility for a new **Master**). To get a better understanding on how to correctly set up Sentinel, please read -the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as +the [Redis Sentinel documentation](https://redis.io/topics/sentinel) first, as failing to configure it correctly can lead to data loss or can bring your whole cluster down, invalidating the failover effort. @@ -885,8 +885,8 @@ Read more on High Availability: [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [gh-531]: https://github.com/redis/redis-rb/issues/531 [gh-534]: https://github.com/redis/redis-rb/issues/534 -[redis]: http://redis.io/ -[sentinel]: http://redis.io/topics/sentinel +[redis]: https://redis.io/ +[sentinel]: https://redis.io/topics/sentinel [omnifile]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb [source]: ../../install/installation.md [ce]: https://about.gitlab.com/downloads diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md index 5823c575251..2101d36d2b6 100644 --- a/doc/administration/high_availability/redis_source.md +++ b/doc/administration/high_availability/redis_source.md @@ -107,7 +107,7 @@ starting with `sentinel` prefix. Assuming that the Redis Sentinel is installed on the same instance as Redis master with IP `10.0.0.1` (some settings might overlap with the master): -1. [Install Redis Sentinel](http://redis.io/topics/sentinel) +1. [Install Redis Sentinel](https://redis.io/topics/sentinel) 1. Edit `/etc/redis/sentinel.conf`: ```conf @@ -363,7 +363,7 @@ production: port: 26379 # point to sentinel, not to redis port ``` -When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel). +When in doubt, please read [Redis Sentinel documentation](https://redis.io/topics/sentinel). [gh-531]: https://github.com/redis/redis-rb/issues/531 [downloads]: https://about.gitlab.com/downloads diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 0e41a38b7e2..038e043281c 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -84,7 +84,7 @@ Introduced in GitLab 10.0, this file lives in It helps you see requests made directly to the API. For example: ```json -{"time":"2017-10-10T12:30:11.579Z","severity":"INFO","duration":16.84,"db":1.57,"view":15.27,"status":200,"method":"POST","path":"/api/v4/internal/allowed","params":{"action":"git-upload-pack","changes":"_any","gl_repository":null,"project":"root/foobar.git","protocol":"ssh","env":"{}","key_id":"[FILTERED]","secret_token":"[FILTERED]"},"host":"127.0.0.1","ip":"127.0.0.1","ua":"Ruby"} +{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30} ``` This entry above shows an access to an internal endpoint to check whether an diff --git a/doc/api/issues.md b/doc/api/issues.md index 57e861bc62e..0dc9d706120 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -37,11 +37,11 @@ GET /issues?my_reaction_emoji=star | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. `No+Milestone` lists all issues with no milestone. `Any+Milestone` lists all issues that have an assigned milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -151,11 +151,11 @@ GET /groups/:id/issues?my_reaction_emoji=star | `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. `No+Milestone` lists all issues with no milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | @@ -265,11 +265,11 @@ GET /projects/:id/issues?my_reaction_emoji=star | `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. `No+Milestone` lists all issues with no milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | @@ -1113,6 +1113,93 @@ Example response: } ``` +## List merge requests related to issue + +Get all the merge requests that are related to the issue. + +``` +GET /projects/:id/issues/:issue_id/related_merge_requests +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project's issue | + +```sh +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests +``` + +Example response: + +```json +[ + { + "id": 29, + "iid": 11, + "project_id": 1, + "title": "Provident eius eos blanditiis consequatur neque odit.", + "description": "Ut consequatur ipsa aspernatur quisquam voluptatum fugit. Qui harum corporis quo fuga ut incidunt veritatis. Autem necessitatibus et harum occaecati nihil ea.\r\n\r\ntwitter/flight#8", + "state": "opened", + "created_at": "2018-09-18T14:36:15.510Z", + "updated_at": "2018-09-19T07:45:13.089Z", + "target_branch": "v2.x", + "source_branch": "so_long_jquery", + "upvotes": 0, + "downvotes": 0, + "author": { + "id": 14, + "name": "Verna Hills", + "username": "lawanda_reinger", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/de68a91aeab1cff563795fb98a0c2cc0?s=80&d=identicon", + "web_url": "https://gitlab.example.com/lawanda_reinger" + }, + "assignee": { + "id": 19, + "name": "Jody Baumbach", + "username": "felipa.kuvalis", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/6541fc75fc4e87e203529bd275fafd07?s=80&d=identicon", + "web_url": "https://gitlab.example.com/felipa.kuvalis" + }, + "source_project_id": 1, + "target_project_id": 1, + "labels": [], + "work_in_progress": false, + "milestone": { + "id": 27, + "iid": 2, + "project_id": 1, + "title": "v1.0", + "description": "Et tenetur voluptatem minima doloribus vero dignissimos vitae.", + "state": "active", + "created_at": "2018-09-18T14:35:44.353Z", + "updated_at": "2018-09-18T14:35:44.353Z", + "due_date": null, + "start_date": null, + "web_url": "https://gitlab.example.com/twitter/flight/milestones/2" + }, + "merge_when_pipeline_succeeds": false, + "merge_status": "cannot_be_merged", + "sha": "3b7b528e9353295c1c125dad281ac5b5deae5f12", + "merge_commit_sha": null, + "user_notes_count": 9, + "discussion_locked": null, + "should_remove_source_branch": null, + "force_remove_source_branch": false, + "web_url": "https://gitlab.example.com/twitter/flight/merge_requests/4", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "squash": false + } +] +``` + ## List merge requests that will close issue on merge Get all the merge requests that will close issue when merged. diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 0291b7e00c2..f3cfe0ad218 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -30,10 +30,10 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `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` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -43,11 +43,11 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me` | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | -| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | +| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | ```json [ @@ -154,10 +154,10 @@ Parameters: | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | yes | The ID of a project | | `iids[]` | Array[integer] | no | Return the request having the given `iid` | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `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` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -167,9 +167,9 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13060] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json @@ -266,11 +266,11 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `id` | integer | yes | The ID of a group | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | -| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `id` | integer | yes | The ID of a group | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -280,9 +280,9 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json diff --git a/doc/api/tags.md b/doc/api/tags.md index f2a3f9f28d2..826900ca518 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -134,7 +134,7 @@ Parameters: "description": "Amazing release. Wow" }, "name": "v1.0.0", - "target: "2695effb5807a22ff3d138d593fd856244e155e7", + "target": "2695effb5807a22ff3d138d593fd856244e155e7", "message": null } ``` diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index 9657f52159e..6aa0edd87b4 100644 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ b/doc/ci/examples/artifactory_and_gitlab/index.md @@ -16,8 +16,8 @@ to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory You'll create two different projects: -- `simple-maven-dep`: the app built and deployed to Artifactory (available at https://gitlab.com/gitlab-examples/maven/simple-maven-dep) -- `simple-maven-app`: the app using the previous one as a dependency (available at https://gitlab.com/gitlab-examples/maven/simple-maven-app) +- `simple-maven-dep`: the app built and deployed to Artifactory (available at https://gitlab.com/gitlab-examples/maven/simple-maven-dep ) +- `simple-maven-app`: the app using the previous one as a dependency (available at https://gitlab.com/gitlab-examples/maven/simple-maven-app ) We assume that you already have a GitLab account on [GitLab.com](https://gitlab.com/), and that you know the basic usage of Git and [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/). We also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it. diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md index 0f79f7d1b17..bc948dc6ea9 100644 --- a/doc/ci/examples/container_scanning.md +++ b/doc/ci/examples/container_scanning.md @@ -63,4 +63,10 @@ are still maintained, they have been deprecated with GitLab 11.0 and may be remo in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. +CAUTION: **Caution:** +Starting with GitLab 11.5, Container Scanning feature is licensed under the name `container_scanning`. +While the old name `sast_container` is still maintained, it has been deprecated with GitLab 11.5 and +may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` +configuration to reflect that change if you are using the `$GITLAB_FEATURES` environment variable. + [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index b2c73caae2e..c0346d78141 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -398,10 +398,10 @@ other reasons][ci-reasons] to keep using GitLab CI/CD. The benefits to our teams - [Using Docker images documentation][using-docker] - [Example project: Hello GitLab CI/CD on GitLab][hello-gitlab] -[phoenix-site]: http://phoenixframework.org/ "Phoenix Framework" +[phoenix-site]: https://phoenixframework.org/ "Phoenix Framework" [phoenix-learning-guide]: https://hexdocs.pm/phoenix/learning.html "Phoenix Learning Guide" -[phoenix-install]: http://www.phoenixframework.org/docs/installation "Phoenix Installation" -[phoenix-mysql]: http://www.phoenixframework.org/docs/using-mysql "Phoenix with MySQL" +[phoenix-install]: https://hexdocs.pm/phoenix/installation.html "Phoenix Installation" +[phoenix-mysql]: https://hexdocs.pm/phoenix/ecto.html#using-mysql "Phoenix with MySQL" [elixir-site]: http://elixir-lang.org/ "Elixir" [elixir-mix]: http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html "Introduction to mix" [elixir-docs]: http://elixir-lang.org/getting-started/introduction.html "Elixir Documentation" diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index 338368dbbc9..b76f9618fc9 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -31,7 +31,7 @@ Database: el_duderino ``` If you are wondering why we used `mysql` for the `Host`, read more at -[How is service linked to the job](../docker/using_docker_images.md#how-is-service-linked-to-the-job). +[How services are linked to the job](../docker/using_docker_images.md#how-services-are-linked-to-the-job). You can also use any other docker image available on [Docker Hub][hub-mysql]. For example, to use MySQL 5.5 the service becomes `mysql:5.5`. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 6c6e198a7c3..95722c027ba 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -379,7 +379,7 @@ let(:mutation) do ) end -it 'returns a successfull response' do +it 'returns a successful response' do post_graphql_mutation(mutation, current_user: user) expect(response).to have_gitlab_http_status(:success) diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 1764e2d8b21..5b32b5cd46f 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -171,6 +171,7 @@ the feature you contribute through all of these steps. 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/), if relevant 1. Community questions answered 1. Answers to questions radiated (in docs/wiki/support etc.) +1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-or-end-to-end-tests) added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) with any questions If you add a dependency in GitLab (such as an operating system package) please consider updating the following and note the applicability of each in your @@ -185,7 +186,7 @@ merge request: 1. Omnibus package creator https://gitlab.com/gitlab-org/omnibus-gitlab [definition-of-done]: http://guide.agilealliance.org/guide/definition-of-done.html -[testing]: ../testing_guide/index.md +[testing]: ../testing_guide/index.md --- diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index 3d8da6accc1..533e2001300 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -3,7 +3,7 @@ We manage our own Icon and Illustration library in the [gitlab-svgs][gitlab-svgs] repository. This repository is published on [npm][npm] and managed as a dependency via yarn. You can browse all available Icons and Illustrations [here][svg-preview]. -To upgrade to a new version run `yarn upgrade @gitlab-org/gitlab-svgs`. +To upgrade to a new version run `yarn upgrade @gitlab/svgs`. ## Icons @@ -111,6 +111,6 @@ export default { </template> ``` -[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs +[npm]: https://www.npmjs.com/package/@gitlab/svgs [gitlab-svgs]: https://gitlab.com/gitlab-org/gitlab-svgs [svg-preview]: https://gitlab-org.gitlab.io/gitlab-svgs diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index dada59ce242..b65fbc9d958 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -152,14 +152,31 @@ in RC1, followed by the feature flag being removed in RC2. This in turn means the feature will be stable by the time we publish a stable package around the 22nd of the month. -## Undefined feature flags default to "on" +## Implicit feature flags -By default, the [`Project#feature_available?`][project-fa], +The [`Project#feature_available?`][project-fa], [`Namespace#feature_available?`][namespace-fa] (EE), and -[`License.feature_available?`][license-fa] (EE) methods will check if the -specified feature is behind a feature flag. Unless the feature is explicitly -disabled or limited to a percentage of users, the feature flag check will -default to `true`. +[`License.feature_available?`][license-fa] (EE) methods all implicitly check for +a feature flag by the same name as the provided argument. + +For example if a feature is license-gated, there's no need to add an additional +explicit feature flag check since the flag will be checked as part of the +`License.feature_available?` call. Similarly, there's no need to "clean up" a +feature flag once the feature has reached general availability. + +You'd still want to use an explicit `Feature.enabled?` check if your new feature +isn't gated by a License or Plan. + +[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68 +[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85 +[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300 + +### Undefined feature flags default to "on" + +An important side-effect of the [implicit feature +flags][#implicit-feature-flags] mentioned above is that unless the feature is +explicitly disabled or limited to a percentage of users, the feature flag check +will default to `true`. As an example, if you were to ship the backend half of a feature behind a flag, you'd want to explicitly disable that flag until the frontend half is also ready @@ -171,7 +188,3 @@ to be shipped. You can do this via ChatOps: Note that you can do this at any time, even before the merge request using the flag has been merged! - -[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68 -[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85 -[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300 diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 4292a17bfa5..4f4ff85fe1d 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -37,9 +37,9 @@ Review Apps are automatically deployed by each pipeline, both in review app manually, and is also started by GitLab once a branch is deleted - [TBD] Review apps are cleaned up regularly using a pipeline schedule that runs the [`scripts/review_apps/automated_cleanup.rb`][automated_cleanup.rb] script -- If you're unable to log in using the `root` username and password the - deployment may have failed. Stop the review app via the `stop_review` - manual job and then retry the `review` job to redeploy the review app. +- If you're unable to log in using the `root` username and password, the + deployment may have failed. Stop the Review App via the `stop_review` + manual job and then retry the `review` job to redeploy the Review App. [^1]: We use the `CNG-mirror` project so that the `CNG`, (**C**loud **N**ative **G**itLab), project's registry is not overloaded with a lot of transient Docker images. diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md index 8348de4f8a2..ceb9ed56ac4 100644 --- a/doc/development/ux_guide/tips.md +++ b/doc/development/ux_guide/tips.md @@ -1,20 +1,16 @@ # Tips -## Contents -* [SVGs](#svgs) - ---- - ## SVGs When exporting SVGs, be sure to follow the following guidelines: 1. Convert all strokes to outlines. -2. Use pathfinder tools to combine overlapping paths and create compound paths. -3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. -4. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. +1. Use pathfinder tools to combine overlapping paths and create compound paths. +1. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. +1. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. + +You can open your SVG in a text editor to ensure that it is clean. -You can open your svg in a text editor to ensure that it is clean. Incorrect files will look like this: ```xml @@ -35,10 +31,10 @@ Incorrect files will look like this: </svg> ``` -Correct file will look like this: +Correct files will look like this: ```xml <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17" enable-background="new 0 0 16 17"><path d="m15.1 1h-2.1v-1h-2v1h-6v-1h-2v1h-2.1c-.5 0-.9.5-.9 1v14c0 .6.4 1 .9 1h14.2c.5 0 .9-.4.9-1v-14c0-.5-.4-1-.9-1m-1.1 14h-12v-9h12v9m0-11h-12v-1h12v1"/><path d="m5.4 11.6l1.5 1.2c.4.3 1.1.3 1.4-.1l2.5-3c.3-.4.3-1.1-.1-1.4-.5-.4-1.1-.3-1.5.1l-1.8 2.2-.8-.6c-.4-.3-1.1-.3-1.4.2-.3.4-.3 1 .2 1.4"/></svg> ``` -> TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo) +> TODO: Checkout <https://github.com/svg/svgo>. diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index 676392eacf2..d67695d75b4 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -1,7 +1,8 @@ # Digital Ocean and Docker Machine test environment -## Warning. This guide is for quickly testing different versions of GitLab and -## not recommended for ease of future upgrades or keeping the data you create. +CAUTION: **Caution:** +This guide is for quickly testing different versions of GitLab and not recommended for ease of +future upgrades or keeping the data you create. ## Initial setup @@ -12,92 +13,88 @@ locally on either macOS or Linux. #### Install Docker Toolbox -1. [https://www.docker.com/products/docker-toolbox](https://www.docker.com/products/docker-toolbox) +- <https://www.docker.com/products/docker-toolbox> ### On Linux #### Install Docker Engine -1. [https://docs.docker.com/engine/installation/linux](https://docs.docker.com/engine/installation/linux/) +- <https://docs.docker.com/engine/installation/linux/> #### Install Docker Machine -1. [https://docs.docker.com/machine/install-machine](https://docs.docker.com/machine/install-machine/) +- <https://docs.docker.com/machine/install-machine/> -_The rest of the steps are identical for macOS and Linux_ +NOTE: **Note:** +The rest of the steps are identical for macOS and Linux. ### Create new docker host -1. Login to Digital Ocean -1. Generate a new API token at https://cloud.digitalocean.com/settings/api/tokens +1. Login to Digital Ocean. +1. Generate a new API token at <https://cloud.digitalocean.com/settings/api/tokens>. + This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. -This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. + NOTE: **Note:** + 4GB is the minimum requirement for a Docker host that will run more than one GitLab instance. -**Note: 4GB is the minimum requirement for a Docker host that will run more then one GitLab instance** + - RAM: 4GB + - Name: `gitlab-test-env-do` + - Driver: `digitalocean` -+ RAM: 4GB -+ Name: `gitlab-test-env-do` -+ Driver: `digitalocean` +1. Set the DO token: + ```sh + export DOTOKEN=<your generated token> + ``` -**Set the DO token** - Replace the string below with your generated token +1. Create the machine: -``` -export DOTOKEN=cf3dfd0662933203005c4a73396214b7879d70aabc6352573fe178d340a80248 -``` - -**Create the machine** - -``` -docker-machine create \ - --driver digitalocean \ - --digitalocean-access-token=$DOTOKEN \ - --digitalocean-size "4gb" \ - gitlab-test-env-do -``` - -+ Resource: https://docs.docker.com/machine/drivers/digital-ocean/ + ```sh + docker-machine create \ + --driver digitalocean \ + --digitalocean-access-token=$DOTOKEN \ + --digitalocean-size "4gb" \ + gitlab-test-env-do + ``` +Resource: <https://docs.docker.com/machine/drivers/digital-ocean/>. ### Creating GitLab test instance - #### Connect your shell to the new machine - In this example we'll create a GitLab EE 8.10.8 instance. - First connect the docker client to the docker host you created previously. -``` +```sh eval "$(docker-machine env gitlab-test-env-do)" ``` You can add this to your `~/.bash_profile` file to ensure the `docker` client uses the `gitlab-test-env-do` docker host - #### Create new GitLab container -+ HTTP port: `8888` -+ SSH port: `2222` - + Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG ` -+ Hostname: IP of docker host -+ Container name: `gitlab-test-8.10` -+ GitLab version: **EE** `8.10.8-ee.0` +- HTTP port: `8888` +- SSH port: `2222` + - Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG` +- Hostname: IP of docker host +- Container name: `gitlab-test-8.10` +- GitLab version: **EE** `8.10.8-ee.0` -##### Set up container settings +##### Set up container settings -``` +```sh export SSH_PORT=2222 export HTTP_PORT=8888 export VERSION=8.10.8-ee.0 export NAME=gitlab-test-8.10 ``` -##### Create container -``` +##### Create container + +```sh docker run --detach \ --env GITLAB_OMNIBUS_CONFIG="external_url 'http://$(docker-machine ip gitlab-test-env-do):$HTTP_PORT'; gitlab_rails['gitlab_shell_ssh_port'] = $SSH_PORT;" \ --hostname $(docker-machine ip gitlab-test-env-do) \ @@ -110,23 +107,20 @@ gitlab/gitlab-ee:$VERSION ##### Retrieve the docker host IP -``` +```sh docker-machine ip gitlab-test-env-do # example output: 192.168.151.134 ``` - -+ Browse to: http://192.168.151.134:8888/ - +Browse to: <http://192.168.151.134:8888/>. ##### Execute interactive shell/edit configuration - -``` +```sh docker exec -it $NAME /bin/bash ``` -``` +```sh # example commands root@192:/# vi /etc/gitlab/gitlab.rb root@192:/# gitlab-ctl reconfigure @@ -134,6 +128,6 @@ root@192:/# gitlab-ctl reconfigure #### Resources -+ [https://docs.gitlab.com/omnibus/docker/](https://docs.gitlab.com/omnibus/docker/) -+ [https://docs.docker.com/machine/get-started/](https://docs.docker.com/machine/get-started/) -+ [https://docs.docker.com/machine/reference/ip/](https://docs.docker.com/machine/reference/ip/)+ +- <https://docs.gitlab.com/omnibus/docker/>. +- <https://docs.docker.com/machine/get-started/>. +- <https://docs.docker.com/machine/reference/ip/>. diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 2b9cce6539f..76f5495ff78 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -9,37 +9,39 @@ You can only restore a backup to **exactly the same version and type (CE/EE)** of GitLab on which it was created. The best way to migrate your repositories from one server to another is through backup restore. -## Backup +## Requirements -GitLab provides a simple command line interface to backup your whole installation, -and is flexible enough to fit your needs. +In order to be able to backup and restore, you need two essential tools +installed on your system. -### Requirements +### Rsync -* rsync +If you installed GitLab: -If you're using GitLab with the Omnibus package, you're all set. If you -installed GitLab from source, make sure you have rsync installed. +- Using the Omnibus package, you're all set. +- From source, make sure `rsync` is installed: -If you're using Ubuntu, you could run: + ```sh + # Debian/Ubuntu + sudo apt-get install rsync -``` -sudo apt-get install -y rsync -``` + # RHEL/CentOS + sudo yum install rsync + ``` -* tar +### Tar Backup and restore tasks use `tar` under the hood to create and extract archives. Ensure you have version 1.30 or above of `tar` available in your system. To check the version, run: -``` +```sh tar --version ``` -### Backup timestamp +## Backup timestamp ->**Note:** +NOTE: **Note:** In GitLab 9.2 the timestamp format was changed from `EPOCH_YYYY_MM_DD` to `EPOCH_YYYY_MM_DD_GitLab_version`, for example `1493107454_2018_04_25` would become `1493107454_2018_04_25_10.6.4-ce`. @@ -54,30 +56,46 @@ available. For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, then the timestamp is `1493107454_2018_04_25_10.6.4-ce`. -### Creating a backup of the GitLab system +## Creating a backup of the GitLab system + +GitLab provides a simple command line interface to backup your whole instance. +It backs up your: + +- Database +- Attachments +- Git repositories data +- CI/CD job output logs +- CI/CD job artifacts +- LFS objects +- Container Registry images +- GitLab Pages content + +CAUTION: **Warning:** +GitLab does not back up any configuration files, SSL certificates, or system files. +You are highly advised to [read about storing configuration files](#storing-configuration-files). Use this command if you've installed GitLab with the Omnibus package: -``` +```sh sudo gitlab-rake gitlab:backup:create ``` Use this if you've installed GitLab from source: -``` +```sh sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production ``` If you are running GitLab within a Docker container, you can run the backup from the host: -``` +```sh docker exec -t <container name> gitlab-rake gitlab:backup:create ``` If you are using the gitlab-omnibus helm chart on a Kubernetes cluster, you can -run the backup task on the gitlab application pod using kubectl +run the backup task on the gitlab application pod using kubectl: -``` +```sh kubectl exec -it <gitlab-gitlab pod> gitlab-rake gitlab:backup:create ``` @@ -110,9 +128,50 @@ Deleting tmp directories...[DONE] Deleting old backups... [SKIPPING] ``` +## Storing configuration files + +A backup performed by the [raketask GitLab provides](#creating-a-backup-of-the-gitlab-system) +does **not** store your configuration files. The primary reason for this is that your +database contains encrypted information for two-factor authentication, the CI/CD +'secure variables', etc. Storing encrypted information along with its key in the +same place defeats the purpose of using encryption in the first place. + +CAUTION: **Warning:** +The secrets file is essential to preserve your database encryption key. + +At the very **minimum**, you must backup: + +For Omnibus: + +- `/etc/gitlab/gitlab-secrets.json` +- `/etc/gitlab/gitlab.rb` + +For installation from source: + +- `/home/git/gitlab/config/secrets.yml` +- `/home/git/gitlab/config/gitlab.yml` + +For [Docker installations](https://docs.gitlab.com/omnibus/docker/), you must +back up the volume where the configuration files are stored. If you have created +the GitLab container according to the documentation, it should be under +`/srv/gitlab/config`. + +You may also want to back up any TLS keys and certificates, and your +[SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). + +If you use Omnibus GitLab, see some additional information +[to backup your configuration](https://docs.gitlab.com/omnibus/settings/backups.html). + +In the unlikely event that the secrets file is lost, see the +[troubleshooting section](#when-the-secrets-file-is-lost). + +## Backup options + +The command line tool GitLab provides to backup your instance can take more options. + ### Backup strategy option -> **Note:** Introduced as an option in GitLab 8.17. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8728) in GitLab 8.17. The default backup strategy is to essentially stream data from the respective data locations to the backup using the Linux command `tar` and `gzip`. This works @@ -129,8 +188,11 @@ so the problem doesn't compound, but it could be a considerable change for large installations. This is why the `copy` strategy is not the default in 8.17. To use the `copy` strategy instead of the default streaming strategy, specify -`STRATEGY=copy` in the Rake task command. For example, -`sudo gitlab-rake gitlab:backup:create STRATEGY=copy`. +`STRATEGY=copy` in the Rake task command. For example: + +```sh +sudo gitlab-rake gitlab:backup:create STRATEGY=copy +``` ### Excluding specific directories from the backup @@ -151,11 +213,15 @@ Use a comma to specify several options at the same time: All wikis will be backed up as part of the `repositories` group. Non-existent wikis will be skipped during a backup. -``` -# use this command if you've installed GitLab with the Omnibus package +For Omnibus GitLab packages: + +```sh sudo gitlab-rake gitlab:backup:create SKIP=db,uploads +``` + +For installations from source: -# if you've installed GitLab from source +```sh sudo -u git -H bundle exec rake gitlab:backup:create SKIP=db,uploads RAILS_ENV=production ``` @@ -208,7 +274,7 @@ This example can be used for a bucket in Amsterdam (AMS3). 1. [Reconfigure GitLab] for the changes to take effect -CAUTION: **Warning:** +NOTE: **Note:** If you see `400 Bad Request` by using Digital Ocean Spaces, the cause may be the usage of backup encryption. Remove or comment the line that contains `gitlab_rails['backup_encryption']` since Digital Ocean Spaces @@ -370,33 +436,43 @@ backups will be copied to, and will be created if it does not exist. If the directory that you want to copy the tarballs to is the root of your mounted directory, just use `.` instead. -For omnibus packages: -```ruby -gitlab_rails['backup_upload_connection'] = { - :provider => 'Local', - :local_root => '/mnt/backups' -} +For Omnibus GitLab packages: -# The directory inside the mounted folder to copy backups to -# Use '.' to store them in the root directory -gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups' -``` +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['backup_upload_connection'] = { + :provider => 'Local', + :local_root => '/mnt/backups' + } + + # The directory inside the mounted folder to copy backups to + # Use '.' to store them in the root directory + gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups' + ``` + +1. [Reconfigure GitLab] for the changes to take effect. + +--- For installations from source: -```yaml - backup: - # snip - upload: - # Fog storage connection settings, see http://fog.io/storage/ . - connection: - provider: Local - local_root: '/mnt/backups' - # The directory inside the mounted folder to copy backups to - # Use '.' to store them in the root directory - remote_directory: 'gitlab_backups' -``` +1. Edit `home/git/gitlab/config/gitlab.yml`: + + ```yaml + backup: + upload: + # Fog storage connection settings, see http://fog.io/storage/ . + connection: + provider: Local + local_root: '/mnt/backups' + # The directory inside the mounted folder to copy backups to + # Use '.' to store them in the root directory + remote_directory: 'gitlab_backups' + ``` + +1. [Restart GitLab] for the changes to take effect. ### Backup archive permissions @@ -405,45 +481,56 @@ will have owner/group git:git and 0600 permissions by default. This is meant to avoid other system users reading GitLab's data. If you need the backup archives to have different permissions you can use the 'archive_permissions' setting. -``` -# In /etc/gitlab/gitlab.rb, for omnibus packages -gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable -``` +For Omnibus GitLab packages: -``` -# In gitlab.yml, for installations from source: - backup: - archive_permissions: 0644 # Makes the backup archives world-readable -``` +1. Edit `/etc/gitlab/gitlab.rb`: -### Storing configuration files + ```ruby + gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable + ``` + +1. [Reconfigure GitLab] for the changes to take effect. + +--- + +For installations from source: -Please be informed that a backup does not store your configuration -files. One reason for this is that your database contains encrypted -information for two-factor authentication. Storing encrypted -information along with its key in the same place defeats the purpose -of using encryption in the first place! +1. Edit `/home/git/gitlab/config/gitlab.yml`: -If you use an Omnibus package please see the [instructions in the readme to backup your configuration](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#backup-and-restore-omnibus-gitlab-configuration). -If you have a cookbook installation there should be a copy of your configuration in Chef. -If you installed from source, please consider backing up your `config/secrets.yml` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). + ```yaml + backup: + archive_permissions: 0644 # Makes the backup archives world-readable + ``` -At the very **minimum** you should backup `/etc/gitlab/gitlab.rb` and -`/etc/gitlab/gitlab-secrets.json` (Omnibus), or -`/home/git/gitlab/config/secrets.yml` (source) to preserve your database -encryption key. +1. [Restart GitLab] for the changes to take effect. ### Configuring cron to make daily backups ->**Note:** +NOTE: **Note:** The following cron jobs do not [backup your GitLab configuration files](#storing-configuration-files) or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). -**For Omnibus installations** +For Omnibus GitLab packages: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + ## Limit backup lifetime to 7 days - 604800 seconds + gitlab_rails['backup_keep_time'] = 604800 + ``` + +1. [Reconfigure GitLab] for the changes to take effect. + +Note that the `backup_keep_time` configuration option only manages local +files. GitLab does not automatically prune old files stored in a third-party +object storage (e.g., AWS S3) because the user may not have permission to list +and delete files. We recommend that you configure the appropriate retention +policy for your object storage. For example, you can configure [the S3 backup +policy as described here](http://stackoverflow.com/questions/37553070/gitlab-omnibus-delete-backup-from-amazon-s3). To schedule a cron job that backs up your repositories and GitLab metadata, use the root user: -``` +```sh sudo su - crontab -e ``` @@ -455,26 +542,24 @@ There, add the following line to schedule the backup for everyday at 2 AM: ``` You may also want to set a limited lifetime for backups to prevent regular -backups using all your disk space. To do this add the following lines to -`/etc/gitlab/gitlab.rb` and reconfigure: +backups using all your disk space. -``` -# limit backup lifetime to 7 days - 604800 seconds -gitlab_rails['backup_keep_time'] = 604800 -``` +--- -Note that the `backup_keep_time` configuration option only manages local -files. GitLab does not automatically prune old files stored in a third-party -object storage (e.g., AWS S3) because the user may not have permission to list -and delete files. We recommend that you configure the appropriate retention -policy for your object storage. For example, you can configure [the S3 backup -policy as described here](http://stackoverflow.com/questions/37553070/gitlab-omnibus-delete-backup-from-amazon-s3). +For installations from source: + +1. Edit `home/git/gitlab/config/gitlab.yml`: -**For installation from source** + ```yaml + backup: + ## Limit backup lifetime to 7 days - 604800 seconds + keep_time: 604800 + ``` -``` -cd /home/git/gitlab -sudo -u git -H editor config/gitlab.yml # Enable keep_time in the backup section to automatically delete old backups +1. [Restart GitLab] for the changes to take effect. + + +```sh sudo -u git crontab -e # Edit the crontab for the git user ``` @@ -711,5 +796,53 @@ Those objects have no influence on the database backup/restore but they give thi For more information see similar questions on postgresql issue tracker[here](http://www.postgresql.org/message-id/201110220712.30886.adrian.klaver@gmail.com) and [here](http://www.postgresql.org/message-id/2039.1177339749@sss.pgh.pa.us) as well as [stack overflow](http://stackoverflow.com/questions/4368789/error-must-be-owner-of-language-plpgsql). +### When the secrets file is lost + +If you have failed to [back up the secrets file](#storing-configuration-files), +then users with 2FA enabled will not be able to log into GitLab. In that case, +you need to [disable 2FA for everyone](../security/two_factor_authentication.md#disabling-2fa-for-everyone). + +In the case of CI/CD, if your project has secure variables set, you might experience +some weird behavior, like stuck jobs or 500 errors. In that case, you can try +deleting the `ci_variables` table from the database. + +CAUTION: **Warning:** +Use the following commands at your own risk, and make sure you've taken a +backup beforehand. + +1. Enter the Rails console: + + For Omnibus GitLab packages: + + ```sh + sudo gitlab-rails dbconsole + ``` + + For installations from source: + + ```sh + sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production + ``` + +1. Check the `ci_variables` table: + + ```sql + SELECT * FROM public."ci_variables"; + ``` + + Those are the variables that you need to delete. + +1. Drop the table: + + ```sql + DELETE FROM ci_variables; + ``` + +1. You may need to reconfigure or restart GitLab for the changes to take + effect. + +You should now be able to visit your project, and the jobs will start +running again. + [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 5db042326f3..c5b7813b285 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -8,163 +8,224 @@ you need a secure communication channel for sharing information. The SSH protocol provides this security and allows you to authenticate to the GitLab remote server without supplying your username or password each time. -For a more detailed explanation of how the SSH protocol works, we advise you to -read [this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process). +For a more detailed explanation of how the SSH protocol works, read +[this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process). -## Locating an existing SSH key pair +## Requirements -Before generating a new SSH key pair check if your system already has one -at the default location by opening a shell, or Command Prompt on Windows, -and running the following command: +The only requirement is to have the OpenSSH client installed on your system. This +comes pre-installed on GNU/Linux and macOS, but not on Windows. -**Windows Command Prompt:** +Depending on your Windows version, there are different methods to work with +SSH keys. -```bash -type %userprofile%\.ssh\id_rsa.pub -``` +### Installing the SSH client for Windows 10 -**Git Bash on Windows / GNU/Linux / macOS / PowerShell:** +Starting with Windows 10, you can +[install the Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) +where you can run Linux distributions directly on Windows, without the overhead +of a virtual machine. Once installed and set up, you'll have the Git and SSH +clients at your disposal. -```bash -cat ~/.ssh/id_rsa.pub -``` +### Installing the SSH client for Windows 8.1 and Windows 7 + +The easiest way to install Git and the SSH client on Windows 8.1 and Windows 7 +is [Git for Windows](https://gitforwindows.com). It provides a BASH +emulation (Git Bash) used for running Git from the command line and the +`ssh-keygen` command that is useful to create SSH keys as you'll learn below. + +NOTE: **Alternative tools:** +Although not explored in this page, you can use some alternative tools. +[Cygwin](https://www.cygwin.com) is a large collection of GNU and open source +tools which provide functionality similar to a Unix distribution. +[PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) +provides a graphical user interface to [create SSH keys](https://tartarus.org/~simon/putty-snapshots/htmldoc/Chapter8.html#pubkey-puttygen). + +## Types of SSH keys and which to choose + +GitLab supports RSA, DSA, ECDSA, and ED25519 keys. Their difference lies on +the signing algorithm, and some of them have advantages over the others. For +more information, you can read this +[nice article on ArchWiki](https://wiki.archlinux.org/index.php/SSH_keys#Choosing_the_authentication_key_type). +We'll focus on ED25519 and RSA and here. + +NOTE: **Note:** +As an admin, you can restrict +[which keys should be permitted and their minimum length](../security/ssh_keys_restrictions.md). +By default, all keys are permitted, which is also the case for +[GitLab.com](../user/gitlab_com/index.md#ssh-host-keys-fingerprints). -If you see a string starting with `ssh-rsa` you already have an SSH key pair -and you can skip the generate portion of the next section and skip to the copy -to clipboard step. -If you don't see the string or would like to generate a SSH key pair with a -custom name continue onto the next step. +## ED25519 SSH keys -Note that Public SSH key may also be named as follows: +Following [best practices](https://linux-audit.com/using-ed25519-openssh-keys-instead-of-dsa-rsa-ecdsa/), +you should always favor [ED25519](https://ed25519.cr.yp.to/) SSH keys, since they +are more secure and have better performance over the other types. -- `id_dsa.pub` -- `id_ecdsa.pub` -- `id_ed25519.pub` +They were introduced in OpenSSH 6.5, so any modern OS should include the +option to create them. If for any reason your OS or the GitLab instance you +interact with doesn't support this, you can fallback to RSA. + +## RSA SSH keys + +RSA keys are the most common ones and therefore the most compatible with +servers that may have an old OpenSSH version. Use them if the GitLab server +doesn't work with ED25519 keys. + +The minimum key size is 1024 bits, defaulting to 2048. If you wish to generate a +stronger RSA key pair, specify the `-b` flag with a higher bit value than the +default. + +The old, default password encoding for SSH private keys keys is +[insecure](https://latacora.singles/2018/08/03/the-default-openssh.html); +it's only a single round of an MD5 hash. Since OpenSSH version 6.5, you should +use the `-o` option to `ssh-keygen` to encode your private key in a new, more +secure format. + +If you already have an RSA SSH key pair to use with GitLab, consider upgrading it +to use the more secure password encryption format by using the following command +on the private key: + +```bash +ssh-keygen -o -f ~/.ssh/id_rsa +``` ## Generating a new SSH key pair -1. To generate a new SSH key pair, use the following command: +Before creating an SSH key pair, make sure to read about the +[different types of keys](#types-of-ssh-keys-and-which-to-choose) to understand +their differences. + +To create a new SSH key pair: - **Git Bash on Windows / GNU/Linux / macOS:** +1. Open a terminal on Linux or macOS, or Git Bash / WSL on Windows. +1. Generate a new ED25519 SSH key pair: ```bash - ssh-keygen -o -t rsa -C "your.email@example.com" -b 4096 + ssh-keygen -t ed25519 -C "email@example.com" ``` - (Note: the `-o` option was introduced in 2014; if this command does not work for you, simply remove the `-o` option and try again) + Or, if you want to use RSA: - **Windows:** + ```bash + ssh-keygen -o -t rsa -b 4096 -C "email@example.com" + ``` - Alternatively on Windows you can download - [PuttyGen](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) - and follow [this documentation article][winputty] to generate a SSH key pair. + The `-C` flag adds a comment in the key in case you have multiple of them + and want to tell which is which. It is optional. 1. Next, you will be prompted to input a file path to save your SSH key pair to. + If you don't already have an SSH key pair, use the suggested path by pressing + <kbd>Enter</kbd>. Using the suggested path will normally allow your SSH client + to automatically use the SSH key pair with no additional configuration. - If you don't already have an SSH key pair use the suggested path by pressing - enter. Using the suggested path will normally allow your SSH client - to automatically use the SSH key pair with no additional configuration. + If you already have an SSH key pair with the suggested file path, you will need + to input a new file path and [declare what host](#working-with-non-default-ssh-key-pair-paths) + this SSH key pair will be used for in your `~/.ssh/config` file. - If you already have a SSH key pair with the suggested file path, you will need - to input a new file path and declare what host this SSH key pair will be used - for in your `.ssh/config` file, see [**Working with non-default SSH key pair paths**](#working-with-non-default-ssh-key-pair-paths) - for more information. +1. Once the path is decided, you will be prompted to input a password to + secure your new SSH key pair. It's a best practice to use a password, + but it's not required and you can skip creating it by pressing + <kbd>Enter</kbd> twice. -1. Once you have input a file path you will be prompted to input a password to - secure your SSH key pair. It is a best practice to use a password for an SSH - key pair, but it is not required and you can skip creating a password by - pressing enter. + If, in any case, you want to add or change the password of your SSH key pair, + you can use the `-p`flag: - NOTE: **Note:** - If you want to change the password of your SSH key pair, you can use - `ssh-keygen -p -o -f <keyname>`. - The `-o` option was added in 2014, so if this command does not work for you, - simply remove the `-o` option and try again. + ``` + ssh-keygen -p -o -f <keyname> + ``` -## Adding a SSH key to your GitLab account +Now, it's time to add the newly created public key to your GitLab account. -1. The next step is to copy the public SSH key as we will need it afterwards. +## Adding an SSH key to your GitLab account - To copy your public SSH key to the clipboard, use the appropriate code below: +1. Copy your **public** SSH key to the clipboard by using one of the commands below + depending on your Operating System: **macOS:** ```bash - pbcopy < ~/.ssh/id_rsa.pub + pbcopy < ~/.ssh/id_ed25519.pub ``` - **GNU/Linux (requires the xclip package):** + **WSL / GNU/Linux (requires the xclip package):** ```bash - xclip -sel clip < ~/.ssh/id_rsa.pub + xclip -sel clip < ~/.ssh/id_ed25519.pub ``` - **Windows Command Line:** + **Git Bash on Windows:** ```bash - type %userprofile%\.ssh\id_rsa.pub | clip + cat ~/.ssh/id_ed25519.pub | clip ``` - **Git Bash on Windows / Windows PowerShell:** + You can also open the key in a graphical editor and copy it from there, + but be careful not to accidentally change anything. - ```bash - cat ~/.ssh/id_rsa.pub | clip - ``` - -1. The final step is to add your public SSH key to GitLab. + NOTE: **Note:** + If you opted to create an RSA key, the name might differ. - Navigate to the 'SSH Keys' tab in your 'Profile Settings'. - Paste your key in the 'Key' section and give it a relevant 'Title'. - Use an identifiable title like 'Work Laptop - Windows 7' or - 'Home MacBook Pro 15'. +1. Add your public SSH key to your GitLab account by clicking your avatar + in the upper right corner and selecting **Settings**. From there on, + navigate to **SSH Keys** and paste your public key in the "Key" section. + If you created the key with a comment, this will appear under "Title". + If not, give your key an identifiable title like _Work Laptop_ or + _Home Workstation_, and click **Add key**. + NOTE: **Note:** If you manually copied your public SSH key make sure you copied the entire - key starting with `ssh-rsa` and ending with your email. + key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email. + +## Testing that everything is set up correctly + +To test whether your SSH key was added correctly, run the following command in +your terminal (replacing `gitlab.com` with your GitLab's instance domain): -1. Optionally you can test your setup by running `ssh -T git@example.com` - (replacing `example.com` with your GitLab domain) and verifying that you - receive a `Welcome to GitLab` message. +```bash +ssh -T git@gitlab.com +``` + +You should receive a _Welcome to GitLab, `@username`!_ message. + +If the welcome message doesn't appear, run SSH's verbose mode by replacing `-T` +with `-vvvT` to understand where the error is. ## Working with non-default SSH key pair paths If you used a non-default file path for your GitLab SSH key pair, you must configure your SSH client to find your GitLab private SSH key -for connections to your GitLab server (perhaps `gitlab.com`). +for connections to GitLab. -For your current terminal session you can do so using the following commands +Open a terminal and use the following commands (replacing `other_id_rsa` with your private SSH key): -**Git Bash on Windows / GNU/Linux / macOS:** - ```bash eval $(ssh-agent -s) ssh-add ~/.ssh/other_id_rsa ``` -To retain these settings you'll need to save them to a configuration file. -For OpenSSH clients this is configured in the `~/.ssh/config` file for some -operating systems. +To retain these settings, you'll need to save them to a configuration file. +For OpenSSH clients this is configured in the `~/.ssh/config` file. In this +file you can set up configurations for multiple hosts, like GitLab.com, your +own GitLab instance, GitHub, Bitbucket, etc. + Below are two example host configurations using their own SSH key: -``` -# GitLab.com server +```conf +# GitLab.com Host gitlab.com -RSAAuthentication yes -IdentityFile ~/.ssh/config/private-key-filename-01 + Preferredauthentications publickey + IdentityFile ~/.ssh/gitlab_com_rsa -# Private GitLab server +# Private GitLab instance Host gitlab.company.com -RSAAuthentication yes -IdentityFile ~/.ssh/config/private-key-filename + Preferredauthentications publickey + IdentityFile ~/.ssh/example_com_rsa ``` -Due to the wide variety of SSH clients and their very large number of -configuration options, further explanation of these topics is beyond the scope -of this document. - -Public SSH keys need to be unique, as they will bind to your account. -Your SSH key is the only identifier you'll have when pushing code via SSH. -That's why it needs to uniquely map to a single user. +Public SSH keys need to be unique to GitLab, as they will bind to your account. +Your SSH key is the only identifier you'll have when pushing code via SSH, +that's why it needs to uniquely map to a single user. ## Deploy keys @@ -240,8 +301,6 @@ not implicitly give any access just by setting them up. How to add your SSH key to Eclipse: https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration -[winputty]: https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen - ## SSH on the GitLab server GitLab integrates with the system-installed SSH daemon, designating a user diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 9546f43eea8..73301394e9f 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -43,7 +43,7 @@ This page gathers all the resources for the topic **Authentication** within GitL ## Third-party resources - [Kanboard Plugin GitLab Authentication](https://github.com/kanboard/plugin-gitlab-auth) -- [Jenkins GitLab OAuth Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+OAuth+Plugin) +- [Jenkins GitLab OAuth Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+OAuth+Plugin) - [Set up Gitlab CE with Active Directory authentication](https://www.caseylabs.com/setup-gitlab-ce-with-active-directory-authentication/) - [How to customize GitLab to support OpenID authentication](http://eric.van-der-vlist.com/blog/2013/11/23/how-to-customize-gitlab-to-support-openid-authentication/) - [Openshift - Configuring Authentication and User Agent](https://docs.openshift.org/latest/install_config/configuring_authentication.html#GitLab) diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 4d4832184e2..96e788666a1 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -225,10 +225,11 @@ Auto DevOps at the project level. ### Enabling/disabling Auto DevOps at the project-level -1. Check that your project doesn't have a `.gitlab-ci.yml`, or if one exists, remove it. +If enabling, check that your project doesn't have a `.gitlab-ci.yml`, or if one exists, remove it. + 1. Go to your project's **Settings > CI/CD > Auto DevOps**. -1. Check the **Default to Auto DevOps pipeline** checkbox. -1. Optionally, but recommended, add in the [base domain](#auto-devops-base-domain) +1. Toggle the **Default to Auto DevOps pipeline** checkbox (checked to enable, unchecked to disable) +1. When enabling, it's optional but recommended to add in the [base domain](#auto-devops-base-domain) that will be used by Auto DevOps to [deploy your application](#auto-deploy) and choose the [deployment strategy](#deployment-strategy). 1. Click **Save changes** for the changes to take effect. @@ -246,12 +247,6 @@ There is also a feature flag to enable Auto DevOps to a percentage of projects which can be enabled from the console with `Feature.get(:force_autodevops_on_by_default).enable_percentage_of_actors(10)`. -### Disable Auto DevOps at the project level - -1. Go to your project's **Settings > CI/CD > Auto DevOps**. -1. Uncheck the **Default to Auto DevOps pipeline** checkbox. -1. Click **Save changes** for the changes to take effect. - ### Deployment strategy > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/38542) in GitLab 11.0. diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index b12e86cb0a9..6326aadcdf2 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -83,6 +83,9 @@ under which this application will be deployed.  1. Once ready, click **Create Kubernetes cluster**. + +NOTE: **Note:** +Do not select `f1-micro` from the **Machine type** dropdown. `f1-micro` machines cannot support a full GitLab installation. After a couple of minutes, the cluster will be created. You can also see its status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). diff --git a/doc/university/README.md b/doc/university/README.md index 5edf92b3b09..f19b1ffd3d9 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -205,7 +205,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project ### 4. External Articles -1. [2011 WSJ article by Marc Andreessen - Software is Eating the World](http://www.wsj.com/articles/SB10001424053111903480904576512250915629460) +1. [2011 WSJ article by Marc Andreessen - Software is Eating the World](https://www.wsj.com/articles/SB10001424053111903480904576512250915629460) 1. [2014 Blog post by Chris Dixon - Software eats software development](http://cdixon.org/2014/04/13/software-eats-software-development/) 1. [2015 Venture Beat article - Actually, Open Source is Eating the World](http://venturebeat.com/2015/12/06/its-actually-open-source-software-thats-eating-the-world/) diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md index 6ff27e495fb..6e0f71017c6 100644 --- a/doc/university/glossary/README.md +++ b/doc/university/glossary/README.md @@ -303,7 +303,7 @@ A [tool](https://docs.gitlab.com/ee/integration/external-issue-tracker.html) use ### Jenkins -An Open Source CI tool written using the Java programming language. [Jenkins](https://jenkins-ci.org/) does the same job as GitLab CI, Bamboo, and Travis CI. It is extremely popular. Related [documentation](https://docs.gitlab.com/ee/integration/jenkins.html). +An Open Source CI tool written using the Java programming language. [Jenkins](https://jenkins.io/) does the same job as GitLab CI, Bamboo, and Travis CI. It is extremely popular. Related [documentation](https://docs.gitlab.com/ee/integration/jenkins.html). ### Jira diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index dccb6cbf071..f3a4d766522 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.md @@ -6,91 +6,90 @@ comments: false --- -# Agenda +## Agenda -1. Brief history of Git -1. GitLab walkthrough -1. Configure your environment -1. Workshop +1. Brief history of Git. +1. GitLab walkthrough. +1. Configure your environment. +1. Workshop. --- -# Git introduction +## Git introduction -https://git-scm.com/about +<https://git-scm.com/about> -- Distributed version control - - Does not rely on connection to a central server - - Many copies of the complete history -- Powerful branching and merging -- Adapts to nearly any workflow -- Fast, reliable and stable file format +- Distributed version control. + - Does not rely on connection to a central server. + - Many copies of the complete history. +- Powerful branching and merging. +- Adapts to nearly any workflow. +- Fast, reliable and stable file format. --- -# Help! +## Help! Use the tools at your disposal when you get stuck. -- Use '`git help <command>`' command -- Use Google -- Read documentation at https://git-scm.com +- Use '`git help <command>`' command. +- Use Google. +- Read documentation at <https://git-scm.com>. --- -# GitLab Walkthrough +## GitLab Walkthrough  --- -# Configure your environment +## Configure your environment - Windows: Install 'Git for Windows' -> https://git-for-windows.github.io +> <https://git-for-windows.github.io> - Mac: Type '`git`' in the Terminal application. > If it's not installed, it will prompt you to install it. -- Debian: '`sudo apt-get install git-all`' -or Red Hat '`sudo yum install git-all`' +- Debian: '`sudo apt-get install git-all`' or Red Hat '`sudo yum install git-all`' --- -# Git Workshop +## Git Workshop -## Overview +### Overview -1. Configure Git -1. Configure SSH Key -1. Create a project -1. Committing -1. Feature branching -1. Merge requests -1. Feedback and Collaboration +1. Configure Git. +1. Configure SSH Key. +1. Create a project. +1. Committing. +1. Feature branching. +1. Merge requests. +1. Feedback and Collaboration. --- -# Configure Git +## Configure Git -One-time configuration of the Git client +One-time configuration of the Git client: -```bash +```sh git config --global user.name "Your Name" git config --global user.email you@example.com ``` --- -# Configure SSH Key +## Configure SSH Key -```bash +```sh ssh-keygen -t rsa -b 4096 -C "you@computer-name" ``` -```bash +```sh # You will be prompted for the following information. Press enter to accept the defaults. Defaults appear in parentheses. Generating public/private rsa key pair. Enter file in which to save the key (/Users/you/.ssh/id_rsa): @@ -102,31 +101,30 @@ The key fingerprint is: 39:fc:ce:94:f4:09:13:95:64:9a:65:c1:de:05:4d:01 you@computer-name ``` -Copy your public key and add it to your GitLab profile +Copy your public key and add it to your GitLab profile: -```bash +```sh cat ~/.ssh/id_rsa.pub ``` -```bash +```sh ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com ``` --- -# Create a project +## Create a project -- Create a project in your user namespace - - Choose to import from 'Any Repo by URL' and use - https://gitlab.com/gitlab-org/training-examples.git +- Create a project in your user namespace. + - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>. - Create a '`development`' or '`workspace`' directory in your home directory. -- Clone the '`training-examples`' project +- Clone the '`training-examples`' project. --- -# Commands +## Commands (project) -``` +```sh mkdir ~/development cd ~/development @@ -141,37 +139,37 @@ cd training-examples --- -# Git concepts +## Git concepts -**Untracked files** +### Untracked files New files that Git has not been told to track previously. -**Working area** +### Working area Files that have been modified but are not committed. -**Staging area** +### Staging area Modified files that have been marked to go in the next commit. --- -# Committing +## Committing -1. Edit '`edit_this_file.rb`' in '`training-examples`' -1. See it listed as a changed file (working area) -1. View the differences -1. Stage the file -1. Commit -1. Push the commit to the remote -1. View the git log +1. Edit '`edit_this_file.rb`' in '`training-examples`'. +1. See it listed as a changed file (working area). +1. View the differences. +1. Stage the file. +1. Commit. +1. Push the commit to the remote. +1. View the git log. --- -# Commands +## Commands (committing) -``` +```sh # Edit `edit_this_file.rb` git status git diff @@ -183,29 +181,29 @@ git log --- -# Feature branching +## Feature branching -- Efficient parallel workflow for teams -- Develop each feature in a branch -- Keeps changes isolated -- Consider a 1-to-1 link to issues -- Push branches to the server frequently - - Hint: This is a cheap backup for your work-in-progress code +- Efficient parallel workflow for teams. +- Develop each feature in a branch. +- Keeps changes isolated. +- Consider a 1-to-1 link to issues. +- Push branches to the server frequently. + - Hint: This is a cheap backup for your work-in-progress code. --- -# Feature branching +## Feature branching steps -1. Create a new feature branch called 'squash_some_bugs' +1. Create a new feature branch called 'squash_some_bugs'. 1. Edit '`bugs.rb`' and remove all the bugs. -1. Commit -1. Push +1. Commit. +1. Push. --- -# Commands +## Commands (feature branching) -``` +```sh git checkout -b squash_some_bugs # Edit `bugs.rb` git status @@ -216,51 +214,50 @@ git push origin squash_some_bugs --- -# Merge requests +## Merge requests -- When you want feedback create a merge request -- Target is the ‘default’ branch (usually master) -- Assign or mention the person you would like to review -- Add 'WIP' to the title if it's a work in progress -- When accepting, always delete the branch -- Anyone can comment, not just the assignee -- Push corrections to the same branch +- When you want feedback create a merge request. +- Target is the ‘default’ branch (usually master). +- Assign or mention the person you would like to review. +- Add 'WIP' to the title if it's a work in progress. +- When accepting, always delete the branch. +- Anyone can comment, not just the assignee. +- Push corrections to the same branch. --- -# Merge requests +## Merge requests steps -**Create your first merge request** +Create your first merge request: -1. Use the blue button in the activity feed -1. View the diff (changes) and leave a comment -1. Push a new commit to the same branch -1. Review the changes again and notice the update +1. Use the blue button in the activity feed. +1. View the diff (changes) and leave a comment. +1. Push a new commit to the same branch. +1. Review the changes again and notice the update. --- -# Feedback and Collaboration +## Feedback and Collaboration -- Merge requests are a time for feedback and collaboration -- Giving feedback is hard -- Be as kind as possible -- Receiving feedback is hard -- Be as receptive as possible -- Feedback is about the best code, not the person. You are not your code +- Merge requests are a time for feedback and collaboration. +- Giving feedback is hard. +- Be as kind as possible. +- Receiving feedback is hard. +- Be as receptive as possible. +- Feedback is about the best code, not the person. You are not your code. --- -# Feedback and Collaboration +## Feedback and Collaboration resources Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests: -[https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review) +<https://github.com/thoughtbot/guides/tree/master/code-review>. -See GitLab merge requests for examples: -[https://gitlab.com/gitlab-org/gitlab-ce/merge_requests](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests) +See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests>. --- -# Explore GitLab projects +## Explore GitLab projects  @@ -274,31 +271,29 @@ See GitLab merge requests for examples: --- -# Tags +## Tags -- Useful for marking deployments and releases -- Annotated tags are an unchangeable part of Git history -- Soft/lightweight tags can be set and removed at will -- Many projects combine an annotated release tag with a stable branch -- Consider setting deployment/release tags automatically +- Useful for marking deployments and releases. +- Annotated tags are an unchangeable part of Git history. +- Soft/lightweight tags can be set and removed at will. +- Many projects combine an annotated release tag with a stable branch. +- Consider setting deployment/release tags automatically. --- -# Tags - -- Create a lightweight tag -- Create an annotated tag -- Push the tags to the remote repository +## Tags steps -**Additional resources** +1. Create a lightweight tag. +1. Create an annotated tag. +1. Push the tags to the remote repository. -[http://git-scm.com/book/en/Git-Basics-Tagging](http://git-scm.com/book/en/Git-Basics-Tagging) +Additional resources: <http://git-scm.com/book/en/Git-Basics-Tagging>. --- -# Commands +## Commands (tags) -``` +```sh git checkout master # Lightweight tag @@ -313,31 +308,31 @@ git push origin --tags --- -# Merge conflicts +## Merge conflicts -- Happen often -- Learning to fix conflicts is hard -- Practice makes perfect +- Happen often. +- Learning to fix conflicts is hard. +- Practice makes perfect. - Force push after fixing conflicts. Be careful! --- -# Merge conflicts +## Merge conflicts steps 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'. -1. Commit and push +1. Commit and push. 1. Checkout master and edit `conflicts.rb`. Add 'Line6' and 'Line7' below 'Line3'. -1. Commit and push to master -1. Create a merge request +1. Commit and push to master. +1. Create a merge request. --- -# Merge conflicts +## Merge conflicts commands After creating a merge request you should notice that conflicts exist. Resolve the conflicts locally by rebasing. -``` +```sh git rebase master # Fix conflicts by editing the files. @@ -350,7 +345,7 @@ git push origin <branch> -f --- -# Rebase with squash +## Rebase with squash You may end up with a commit log that looks like this: @@ -368,11 +363,11 @@ Squash these in to meaningful commits using an interactive rebase. --- -# Rebase with squash +## Rebase with squash commands Squash the commits on the same branch we used for the merge conflicts step. -``` +```sh git rebase -i master ``` @@ -380,17 +375,17 @@ In the editor, leave the first commit as 'pick' and set others to 'fixup'. --- -# Questions? +## Questions?  Thank you for your hard work! -**Additional Resources** +## Additional Resources -GitLab Documentation [http://docs.gitlab.com](http://docs.gitlab.com/) -GUI Clients [http://git-scm.com/downloads/guis](http://git-scm.com/downloads/guis) -Pro git book [http://git-scm.com/book](http://git-scm.com/book) -Platzi Course [https://courses.platzi.com/courses/git-gitlab/](https://courses.platzi.com/courses/git-gitlab/) -Code School tutorial [http://try.github.io/](http://try.github.io/) -Contact Us at `subscribers@gitlab.com` +- GitLab Documentation: <http://docs.gitlab.com/>. +- GUI Clients: <http://git-scm.com/downloads/guis>. +- Pro git book: <http://git-scm.com/book>. +- Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>. +- Code School tutorial: <http://try.github.io/>. +- Contact us at `subscribers@gitlab.com`. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 35a9d7adb28..bd0155dc712 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -42,7 +42,11 @@ not send any project names, usernames, or any other specific data. The information from the usage ping is not anonymous, it is linked to the hostname of the instance. -You can view the exact JSON payload in the administration panel. +You can view the exact JSON payload in the administration panel. To view the payload: + +1. Go to the **Admin area** (spanner symbol on the top bar). +1. Expand **Settings** in the left sidebar and click on **Metrics and profiling**. +1. Expand **Usage statistics** and click on the **Preview payload** button. ### Deactivate the usage ping diff --git a/doc/user/markdown.md b/doc/user/markdown.md index f9bdaea185b..96a509c4b21 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,17 +1,8 @@ # Markdown -## GitLab Flavored Markdown (GFM) - -> **Note:** -> Not all of the GitLab-specific extensions to Markdown that are described in -> this document currently work on our documentation website. -> -> For the best result, we encourage you to check this document out as rendered -> by GitLab: [markdown.md] - -_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the [Redcarpet Ruby library][redcarpet]._ +This markdown guide is valid for GitLab's system markdown entries and files. -_Where there are significant differences, we will try to call them out in this document._ +## GitLab Flavored Markdown (GFM) GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). @@ -26,11 +17,28 @@ You can use GFM in the following areas: - markdown documents inside the repository You can also use other rich text files in GitLab. You might have to install a -dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. +dependency to do so. Please see the [`github-markup` gem readme](https://github.com/gitlabhq/markup#markups) for more information. + +> **Notes:** +> +> For the best result, we encourage you to check this document out as rendered +> by GitLab itself: [markdown.md] +> +> As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown +processing of all new issues, merge requests, comments, and other Markdown content +in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the +repositories are also processed with CommonMark. Older content in issues/comments +are still processed using the [Redcarpet Ruby library][redcarpet]. +> +> _Where there are significant differences, we will try to call them out in this document._ ### Transitioning to CommonMark -You may have Markdown documents in your repository that were written using some of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a slightly stricter syntax, these documents may now display a little strangely since we've transitioned to CommonMark. Numbered lists with nested lists in particular can be displayed incorrectly. +You may have Markdown documents in your repository that were written using some +of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a +slightly stricter syntax, these documents may now display a little strangely +since we've transitioned to CommonMark. Numbered lists with nested lists in +particular can be displayed incorrectly. It is usually quite easy to fix. In the case of a nested list such as this: @@ -50,11 +58,18 @@ simply add a space to each nested item: In the documentation below, we try to highlight some of the differences. -If you have a need to view a document using RedCarpet, you can add the token `legacy_render=1` to the end of the url, like this: +If you have a need to view a document using RedCarpet, you can add the token +`legacy_render=1` to the end of the url, like this: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md?legacy_render=1 -If you have a large volume of Markdown files, it can be tedious to determine if they will be displayed correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) tool (not an officially supported product) to generate a list of files and differences between how RedCarpet and CommonMark render the files. It can give you a great idea if anything needs to be changed - many times nothing will need to changed. +If you have a large volume of Markdown files, it can be tedious to determine +if they will be displayed correctly or not. You can use the +[diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) +tool (not an officially supported product) to generate a list of files and +differences between how RedCarpet and CommonMark render the files. It can give +you a great idea if anything needs to be changed - many times nothing will need +to changed. ### Newlines @@ -63,7 +78,8 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newline GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec]. -A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. +A paragraph is simply one or more consecutive lines of text, separated by one or +more blank lines. Line-breaks, or soft returns, are rendered if you end a line with two or more spaces: <!-- (Do *NOT* remove the two ending whitespaces in the following line.) --> @@ -85,7 +101,9 @@ Sugar is sweet > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words -It is not reasonable to italicize just _part_ of a word, especially when you're dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words: +It is not reasonable to italicize just _part_ of a word, especially when you're +dealing with code and names that often appear with multiple underscores. +Therefore, GFM ignores multiple underscores in words: perform_complicated_task @@ -124,7 +142,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multili On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines, GFM supports multiline blockquotes fenced by <code>>>></code>: -```no-highlight +``` >>> If you paste a message from somewhere else @@ -158,7 +176,7 @@ Blocks of code are either fenced by lines with three back-ticks <code>```</code> or are indented with four spaces. Only the fenced code blocks support syntax highlighting: -```no-highlight +``` Inline `code` has `back-ticks around` it. ``` @@ -248,21 +266,23 @@ However the wrapping tags cannot be mixed as such: > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji - Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: +``` +Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: - :zap: You can use emoji anywhere GFM is supported. :v: +:zap: You can use emoji anywhere GFM is supported. :v: - You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. - If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. +If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. - Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: +Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: - Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. +Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. - On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. +On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. - Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +``` Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px">. Well we have a gift for you: @@ -281,7 +301,6 @@ On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/he Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. - ### Special GitLab References GFM recognizes special references. @@ -343,7 +362,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-li You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so: -```no-highlight +``` - [x] Completed task - [ ] Incomplete task - [ ] Sub-task 1 @@ -355,7 +374,7 @@ You can add task lists to issues, merge requests and comments. To create a task Tasks formatted as ordered lists are supported as well: -```no-highlight +``` 1. [x] Completed task 1. [ ] Incomplete task 1. [ ] Sub-task 1 @@ -412,7 +431,7 @@ This math is inline . This is on a separate line -<div align="center"><img src="./img/math_inline_sup_render_gfm.png" ></div> +<img src="./img/math_inline_sup_render_gfm.png" > _Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._ @@ -440,7 +459,7 @@ Examples: `HSL(540,70%,50%)` `HSLA(540,70%,50%,0.7)` -Become: +Becomes:  @@ -482,7 +501,7 @@ For details see the [Mermaid official page][mermaid]. ### Headers -```no-highlight +``` # H1 ## H2 ### H3 @@ -540,7 +559,7 @@ Note that the Emoji processing happens before the header IDs are generated, so t Examples: -```no-highlight +``` Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with **asterisks** or __underscores__. @@ -550,7 +569,7 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` -Become: +Becomes: Emphasis, aka italics, with *asterisks* or _underscores_. @@ -564,7 +583,7 @@ Strikethrough uses two tildes. ~~Scratch this.~~ Examples: -```no-highlight +``` 1. First ordered list item 2. Another item * Unordered sub-list. @@ -577,7 +596,7 @@ Examples: + Or pluses ``` -Become: +Becomes: 1. First ordered list item 2. Another item @@ -595,7 +614,7 @@ each subsequent paragraph should be indented to the same level as the start of t Example: -```no-highlight +``` 1. First ordered list item Second paragraph of first item. @@ -616,7 +635,7 @@ the paragraph will appear outside the list, instead of properly indented under t Example: -```no-highlight +``` 1. First ordered list item Paragraph of first item. @@ -676,7 +695,7 @@ Examples: [logo]: img/markdown_logo.png -Become: +Becomes: Here's our logo: @@ -694,7 +713,7 @@ Reference-style: Examples: -```no-highlight +``` > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -703,7 +722,7 @@ Quote break. > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. ``` -Become: +Becomes: > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -720,7 +739,7 @@ See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubyd Examples: -```no-highlight +``` <dl> <dt>Definition list</dt> <dd>Is something people use sometimes.</dd> @@ -730,7 +749,7 @@ Examples: </dl> ``` -Become: +Becomes: <dl> <dt>Definition list</dt> @@ -788,7 +807,7 @@ ___ Underscores ``` -Become: +Becomes: Three or more... @@ -826,7 +845,7 @@ This line is *on its own line*, because the previous line ends with two spaces. spaces. ``` -Become: +Becomes: Here's a line for us to start with. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 48004471f0a..762d254d6cc 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -113,6 +113,14 @@ To add an existing Kubernetes cluster to your project: After a couple of minutes, your cluster will be ready to go. You can now proceed to install some [pre-defined applications](#installing-applications). +To determine the: + +- API URL, run `kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}'`. +- Token: + 1. List the secrets by running: `kubectl get secrets`. Note the name of the secret you need the token for. + 1. Get the token for the appropriate secret by running: `kubectl get secret <SECRET_NAME> -o jsonpath="{['data']['token']}" | base64 -D`. +- CA certificate, run `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D`. + ## Security implications CAUTION: **Important:** diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md new file mode 100644 index 00000000000..3b81e439119 --- /dev/null +++ b/doc/user/project/clusters/runbooks/index.md @@ -0,0 +1,49 @@ +# Runbooks + +Runbooks are a collection of documented procedures that explain how to +carry out a particular process, be it starting, stopping, debugging, +or troubleshooting a particular system. + +## Overview + +Historically, runbooks took the form of a decision tree or a detailed +step-by-step guide depending on the condition or system. + +Modern implementations have introduced the concept of an "executable +runbooks", where along with a well define process, operators can execute +code blocks or database queries against a given environment. + +## Nurtch Executable Runbooks + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4. + +The JupyterHub app offered via GitLab’s Kubernetes integration now ships +with Nurtch’s Rubix library, providing a simple way to create DevOps +runbooks. A sample runbook is provided, showcasing common operations. + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch this [video](https://www.youtube.com/watch?v=Q_OqHIIUPjE) +for an overview of how this is acomplished in GitLab!** + +## Requirements + +To create an executable runbook, you will need: + +1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. + The simplest way to get started is to add a cluster using [GitLab's GKE integration](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab). +1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install + all the other applications. It is installed in its own pod inside the cluster which + can run the helm CLI in a safe environment. +1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based + virtual hosting. It acts as a web proxy for your applications. +1. **JupyterHub** - JupyterHub is a multi-user service for managing notebooks across + a team. Jupyter Notebooks provide a web-based interactive programming environment + used for data analysis, visualization, and machine learning. + +## Nurtch + +Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is +an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. +Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified +down to a couple of lines of code. Check the [Nurtch Documentation](http://docs.nurtch.com/en/latest) +for more information. diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 4ea35a30bbf..2f5efbe84d9 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -1,6 +1,7 @@ # Migrating projects to a GitLab instance -1. [From Bitbucket.org](bitbucket.md) +1. [From Bitbucket Cloud (aka bitbucket.org)](bitbucket.md) +1. [From Bitbucket Server (aka Stash)](bitbucket_server.md) 1. [From ClearCase](clearcase.md) 1. [From CVS](cvs.md) 1. [From FogBugz](fogbugz.md) diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index f5ea350a58f..9e2434c02ec 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -176,8 +176,8 @@ Clicking on the current board name in the upper left corner will reveal a menu from where you can create another Issue Board and rename or delete the existing one. -Clicking on the main issue board link will take you to the last board -you visited. +When you're revisiting an issue board in a project or group with multiple boards, +GitLab will automatically load the last board you visited. NOTE: **Note:** The Multiple Issue Boards feature is available for diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f9ebf277125..0a7f7d37384 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -236,6 +236,35 @@ all your changes will be available to preview by anyone with the Review Apps lin Find out about [bulk editing merge requests](../../project/bulk_editing.md). +## Troubleshooting + +Sometimes things don't go as expected in a merge request, here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur for one of two reasons: + +* Sidekiq doesn't pick up the changes fast enough +* Because of the bug described in [#41545](https://gitlab.com/gitlab-org/gitlab-ce/issues/41545) + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status will update automatically. + +#### Bug + +Merge Request pipeline statuses can't be retrieved when the following occurs: + +1. A Merge Requst is created +1. The Merge Request is closed +1. Changes are made in the project +1. The Merge Request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +Merge Request again. + ## Tips Here are some tips that will help you be more efficient with merge requests in diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index e1eede8bbed..89b9621b8b9 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -212,7 +212,7 @@ security measure, necessary just for big companies, like banks and shoppings sit with financial transactions. Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): -> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](http://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ +> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ Therefore, the reason why certificates are so important is that they encrypt the connection between the **client** (you, me, your visitors) diff --git a/doc/user/search/img/issues_filter_none_any.png b/doc/user/search/img/issues_filter_none_any.png Binary files differnew file mode 100644 index 00000000000..9682fc55315 --- /dev/null +++ b/doc/user/search/img/issues_filter_none_any.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 4f1b96b775c..3f9d07dacaa 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -40,6 +40,16 @@ The same process is valid for merge requests. Navigate to your project's **Merge and click **Search or filter results...**. Merge requests can be filtered by author, assignee, milestone, and label. +### Filtering by **None** / **Any** + +Some filter fields like milestone and assignee, allow you to filter by **None** or **Any**. + + + +Selecting **None** returns results that have an empty value for that field. E.g.: no milestone, no assignee. + +Selecting **Any** does the opposite. It returns results that have a non-empty value for that field. + ### Searching for specific terms You can filter issues and merge requests by specific terms included in titles or descriptions. diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 731c9209224..c590ac4b0ba 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -10,31 +10,32 @@ You can find notification settings under the user profile. Notification settings are divided into three groups: -* Global Settings -* Group Settings -* Project Settings +- Global settings +- Group settings +- Project settings Each of these settings have levels of notification: -* Disabled - turns off notifications -* Participating - receive notifications from related resources -* Watch - receive notifications from projects or groups user is a member of -* Global - notifications as set at the global settings -* Custom - user will receive notifications when mentioned, is participant and custom selected events. +- Watch: Receive notifications for any activity. +- On Mention: Receive notifications when `@mentioned` in comments. +- Participate: Receive notifications for threads you have participated in. +- Disabled: Turns off notifications. +- Custom: Receive notifications for custom selected events. +- Global: For groups and projects, notifications as per global settings. -#### Global Settings +### Global Settings -Global Settings are at the bottom of the hierarchy. +Global settings are at the bottom of the hierarchy. Any setting set here will be overridden by a setting at the group or a project level. Group or Project settings can use `global` notification setting which will then use anything that is set at Global Settings. -#### Group Settings +### Group Settings  -Group Settings are taking precedence over Global Settings but are on a level below Project or Subgroup Settings: +Group settings are taking precedence over Global Settings but are on a level below Project or Subgroup settings: ``` Group < Subgroup < Project @@ -46,11 +47,11 @@ Organization like this is suitable for users that belong to different groups but same need for being notified for every group they are member of. These settings can be configured on group page under the name of the group. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown. -#### Project Settings +### Project Settings  -Project Settings are at the top level and any setting placed at this level will take precedence of any +Project settings are at the top level and any setting placed at this level will take precedence of any other setting. This is suitable for users that have different needs for notifications per project basis. These settings can be configured on project page under the name of the project. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown. @@ -73,11 +74,12 @@ Below is the table of events users can be notified of: ### Issue / Merge request events In most of the below cases, the notification will be sent to: + - Participants: - the author and assignee of the issue/merge request - 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 + - 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" - Subscribers: anyone who manually subscribed to the issue/merge request @@ -90,12 +92,16 @@ In most of the below cases, the notification will be sent to: | Reassign issue | The above, plus the old assignee | | Reopen issue | | | Due issue | Participants and Custom notification level with this event selected | +| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Remove milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | | New merge request | | | Push to merge request | Participants and Custom notification level with this event selected | | Reassign merge request | The above, plus the old assignee | | Close merge request | | | Reopen merge request | | | Merge merge request | | +| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Remove milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | | New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | | 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 | @@ -129,16 +135,19 @@ Notification emails include headers that provide extra content about the notific | X-GitLab-NotificationReason | The reason for being notified. "mentioned", "assigned", etc | #### X-GitLab-NotificationReason + This header holds the reason for the notification to have been sent out, where reason can be `mentioned`, `assigned`, `own_activity`, etc. Only one reason is sent out according to its priority: + - `own_activity` - `assigned` - `mentioned` -The reason in this header will also be shown in the footer of the notification email. For example an email with the +The reason in this header will also be shown in the footer of the notification email. For example an email with the reason `assigned` will have this sentence in the footer: `"You are receiving this email because you have been assigned an item on {configured GitLab hostname}"` -**Note: Only reasons listed above have been implemented so far** -Further implementation is [being discussed here](https://gitlab.com/gitlab-org/gitlab-ce/issues/42062) +NOTE: **Note:** +Only reasons listed above have been implemented so far. +Further implementation is [being discussed](https://gitlab.com/gitlab-org/gitlab-ce/issues/42062). |
